18. Documentación de APIs: endpoints, parámetros, respuestas, errores y ejemplos
18.1 Introducción
Una API permite que sistemas, aplicaciones o módulos se comuniquen entre sí. La documentación de APIs explica cómo usar esa interfaz correctamente: qué operaciones existen, qué datos se envían, qué respuestas se reciben, qué errores pueden ocurrir y qué reglas deben respetarse.
Una API puede estar técnicamente disponible, pero ser difícil de integrar si su documentación es incompleta. Quien consume la API necesita conocer el contrato con precisión. Cualquier ambigüedad puede producir errores, integraciones frágiles o consultas repetidas al equipo proveedor.
En este tema trabajaremos con documentación de endpoints, métodos, parámetros, autenticación, respuestas, errores, ejemplos, versionado y pruebas de contrato.
18.2 Qué es documentar una API
Documentar una API significa describir su contrato de uso. El contrato define qué puede pedir un consumidor, qué debe enviar, qué recibirá, qué condiciones debe cumplir y cómo interpretar errores.
La documentación de API debe ser precisa porque suele ser usada por personas o equipos que no conocen la implementación interna. Pueden ser desarrolladores del mismo proyecto, otros equipos de la organización, clientes externos o sistemas automatizados.
18.3 Elementos de una API documentada
La imagen muestra los elementos principales de la documentación de APIs: endpoints, métodos, autenticación, parámetros, cuerpo de solicitud, respuestas, errores, ejemplos, versionado y pruebas de contrato.
18.4 Endpoints y métodos
Un endpoint es una dirección o punto de acceso de la API. En APIs HTTP suele combinarse con un método, como GET, POST, PUT, PATCH o DELETE. La documentación debe indicar qué operación realiza cada endpoint y cuándo corresponde usarlo.
Por ejemplo, GET /turnos puede consultar turnos, mientras que POST /turnos puede crear una reserva. Aunque parezcan similares, tienen comportamientos, parámetros y respuestas diferentes.
También conviene indicar si la operación es segura, si modifica datos, si es idempotente y qué permisos requiere.
18.5 Parámetros
Los parámetros son datos que el consumidor envía a la API. Pueden estar en la ruta, en la consulta, en encabezados o en el cuerpo de la solicitud. Documentarlos correctamente es fundamental.
Para cada parámetro conviene indicar nombre, ubicación, tipo de dato, obligatoriedad, descripción, formato, valores permitidos, ejemplo y reglas de validación. Si un parámetro es opcional, debe explicarse qué ocurre cuando no se envía.
Por ejemplo, en GET /turnos?fecha=2026-06-10, el parámetro fecha debería tener formato documentado y comportamiento claro si se omite.
18.6 Cuerpo de solicitud
Cuando una API recibe datos complejos, suele usar un cuerpo de solicitud. La documentación debe describir su estructura, campos, tipos, reglas y ejemplos. Si se usa JSON, conviene mostrar un ejemplo válido.
Para crear una reserva, el cuerpo puede incluir identificador de paciente, profesional, fecha, hora y motivo. Cada campo debe tener significado claro. No alcanza con mostrar un ejemplo si no se explica qué es obligatorio y qué validaciones se aplican.
También debe indicarse el tipo de contenido esperado, como application/json.
18.7 Autenticación y autorización
La documentación debe explicar cómo autenticarse y qué permisos se requieren. Puede indicar uso de tokens, claves, sesiones, OAuth, JWT u otros mecanismos. También debe aclarar roles o alcances necesarios para cada operación.
Autenticación responde quién es el consumidor. Autorización responde qué puede hacer. Un usuario autenticado puede no tener permiso para cancelar turnos de otro paciente o consultar datos administrativos.
Si una API tiene permisos por endpoint, conviene documentarlos junto a cada operación.
18.8 Respuestas exitosas
La documentación debe indicar qué devuelve la API cuando la operación es exitosa. Esto incluye código de estado, encabezados relevantes, cuerpo de respuesta, tipos de datos, ejemplos y significado de cada campo.
Por ejemplo, al crear un turno puede devolverse código 201, identificador de reserva, estado, fecha, hora y datos básicos del profesional. El consumidor necesita saber si esos datos son completos, si pueden ser nulos y si cambian según permisos.
18.9 Errores
Documentar errores es tan importante como documentar respuestas exitosas. Los consumidores necesitan saber qué puede fallar, cómo identificarlo y qué acción tomar. Los errores deben incluir códigos de estado, códigos internos, mensajes y condiciones que los provocan.
Por ejemplo, una reserva puede fallar porque el usuario no está autenticado, no tiene permisos, el horario no existe, el horario ya fue ocupado o los datos enviados son inválidos. Cada caso debería tener una respuesta clara.
Una API que devuelve siempre un error genérico obliga a los consumidores a adivinar causas y dificulta soporte.
18.10 Ejemplos de solicitud y respuesta
Los ejemplos son una de las partes más útiles de la documentación de API. Deben mostrar solicitudes reales o realistas y respuestas completas. Conviene incluir al menos un ejemplo exitoso y ejemplos de errores frecuentes.
{ "pacienteId": 25, "profesionalId": 8, "fecha": "2026-06-10", "hora": "10:00" }
201 Created
{ "turnoId": 1840, "estado": "reservado", "fecha": "2026-06-10", "hora": "10:00" }
El ejemplo no reemplaza la descripción de campos, pero acelera la comprensión.
18.11 Tabla de parámetros
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
pacienteId |
Número | Sí | Identificador del paciente que reserva el turno. |
profesionalId |
Número | Sí | Identificador del profesional seleccionado. |
fecha |
Fecha | Sí | Fecha del turno en formato año-mes-día. |
hora |
Texto | Sí | Hora del turno en formato horas:minutos. |
18.12 Tabla de errores
| Código HTTP | Código interno | Causa | Acción recomendada |
|---|---|---|---|
| 400 | DATOS_INVALIDOS | Faltan campos o tienen formato incorrecto. | Corregir la solicitud. |
| 401 | NO_AUTENTICADO | No se envió credencial válida. | Autenticarse nuevamente. |
| 403 | SIN_PERMISO | El usuario no puede realizar la operación. | Verificar rol o permisos. |
| 409 | TURNO_OCUPADO | El horario ya fue reservado. | Seleccionar otro horario. |
18.13 Versionado de APIs
Cuando una API cambia, puede afectar a consumidores existentes. Por eso, la documentación debe indicar versión, compatibilidad y cambios relevantes. Si existen varias versiones activas, cada una debe tener documentación clara.
Un cambio compatible puede agregar un campo opcional. Un cambio incompatible puede renombrar un campo, eliminar una respuesta o cambiar significado de un estado. Estos cambios deben comunicarse y documentarse con cuidado.
18.14 Contratos y pruebas
La documentación de API define un contrato. Ese contrato debe verificarse. Las pruebas de contrato ayudan a confirmar que la API responde según lo documentado y que los consumidores no dependen de comportamientos accidentales.
Cuando se usa una especificación como OpenAPI, puede generarse documentación, validación y pruebas a partir de un contrato formal. Esto reduce diferencias entre documentación e implementación.
18.15 Herramientas de documentación
Existen herramientas para documentar APIs, como especificaciones OpenAPI, Swagger UI, Redoc, Postman, colecciones de pruebas y sitios generados automáticamente. Estas herramientas pueden mejorar consistencia y actualización.
Sin embargo, una herramienta no garantiza buena documentación. Sigue siendo necesario escribir descripciones claras, ejemplos útiles, errores completos y reglas de negocio relacionadas.
18.16 Errores frecuentes
Al documentar APIs suelen aparecer estos errores:
- Listar endpoints sin explicar propósito ni reglas.
- No indicar autenticación o permisos requeridos.
- Omitir parámetros opcionales y su comportamiento por defecto.
- Mostrar ejemplos incompletos o desactualizados.
- No documentar errores frecuentes.
- No aclarar cambios de versión o compatibilidad.
- Dejar que la implementación y la documentación evolucionen separadas.
18.17 Qué debes recordar de este tema
- La documentación de API describe un contrato de integración.
- Debe incluir endpoints, métodos, parámetros, autenticación, respuestas y errores.
- Los ejemplos aceleran la comprensión y reducen dudas.
- Los errores deben ser tan claros como las respuestas exitosas.
- El versionado es necesario cuando los cambios pueden afectar consumidores.
- Las pruebas de contrato ayudan a mantener coherencia entre documentación e implementación.
- Las herramientas ayudan, pero no reemplazan la claridad del contenido.
18.18 Conclusión
Una API bien documentada facilita integraciones confiables. Al describir endpoints, parámetros, respuestas, errores y ejemplos, la documentación reduce ambigüedad y permite que otros equipos consuman la interfaz con seguridad.
En el próximo tema estudiaremos la documentación de bases de datos: modelo, tablas, restricciones, índices y migraciones.