Plantilla de Documentación de API

Estructura de la plantilla

Usa esta plantilla como base para documentar cualquier API HTTP. Reemplaza las secciones entre corchetes con el contenido específico de tu API.

---

1. Visión general

Base URL

https://api.example.com/v1

Autenticación

Todos los endpoints requieren un Bearer token en el header Authorization:

Authorization: Bearer <your_api_key>

Content-Type

Requests y responses usan application/json a menos que se especifique lo contrario.

Rate Limits

• 100 requests por minuto para usuarios autenticados
• 10 requests por minuto para usuarios anónimos
• Headers de rate limit incluidos en todas las responses:
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

---

2. Endpoints

[Nombre del Recurso]

GET /[resource]

Lista todos los [recursos] con filtrado y paginación opcionales.

Query Parameters

Parámetro	Tipo	Requerido	Descripción
page	integer	No	Número de página (default: 1)
limit	integer	No	Items por página (default: 20, max: 100)
sort	string	No	Campo y dirección de ordenamiento (created_at:desc)
filter[field]	string	No	Filtrar por valor de campo

Response 200 OK

{
  "data": [
    {
      "id": "string",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "total_pages": 5
  }
}

POST /[resource]

Crea un nuevo [recurso].

Request Body

{
  "name": "string (requerido, max 255 chars)",
  "description": "string (opcional, max 1000 chars)"
}

Response 201 Created

{
  "id": "string",
  "name": "string",
  "description": "string",
  "created_at": "2026-01-01T00:00:00Z"
}

GET /[resource]/{id}

Obtiene un [recurso] por ID.

Path Parameters

Parámetro	Tipo	Requerido	Descripción
id	string	Sí	Identificador único del recurso

Response 200 OK

{
  "id": "string",
  "name": "string",
  "description": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

PATCH /[resource]/{id}

Actualiza parcialmente un [recurso]. Solo los campos proporcionados son modificados.

Request Body

{
  "name": "string (opcional)",
  "description": "string (opcional)"
}

Response 200 OK

{
  "id": "string",
  "name": "string",
  "description": "string",
  "updated_at": "2026-01-01T00:00:00Z"
}

DELETE /[resource]/{id}

Elimina un [recurso] por ID.

Response 204 No Content

---

3. Error Responses

Todos los errores siguen esta estructura:

{
  "error": {
    "code": "invalid_request",
    "message": "Descripción legible por humanos",
    "details": [
      {
        "field": "name",
        "issue": "is required"
      }
    ]
  }
}

Códigos HTTP comunes

Status	Código	Descripción
400	bad_request	Request malformado o error de validación
401	unauthorized	Autenticación faltante o inválida
403	forbidden	Permisos insuficientes
404	not_found	El recurso no existe
409	conflict	Conflicto de recurso (ej. campo único duplicado)
422	unprocessable_entity	Error de validación semántica
429	rate_limited	Demasiados requests
500	internal_error	Error del lado del servidor

---

4. SDKs y herramientas

• cURL: Todos los ejemplos usan comandos cURL estándar
• Postman: Importa nuestro spec de OpenAPI
• OpenAPI: Spec auto-generado disponible en /openapi.json

---

5. Changelog

Versión	Fecha	Cambios
1.0.0	2026-06-10	Release inicial

---

Guía de personalización

1. Reemplaza [resource] con tu entidad de dominio real (ej. users, orders, products)
2. Agrega query parameters y campos de response específicos de cada endpoint
3. Incluye ejemplos de autenticación para OAuth, API keys o JWT
4. Agrega ejemplos de código en Python, JavaScript y Java
5. Linkea a tu spec de OpenAPI/Swagger para documentación interactiva