Lección 12 de 12 · Lectura y práctica
Documentar tu API: contratos y ejemplos
Documentacion Una API sin docs es soporte infinito. Documenta endpoints, inputs, outputs y errores. Conceptos clave OpenAPI (idea) Ejemplos reales de request/response Errores documentados Ejemplo Documenta al menos: POST /signup,.
Del concepto a la práctica
Taller de esta lección
Documentar un endpoint significa hacer explícitos método, ruta, parámetros, cuerpo, respuestas y errores. Un ejemplo debe coincidir con la validación real; de lo contrario la documentación se convierte en una prueba engañosa.
Ejemplo resuelto
Para POST /courses, documenta el cuerpo { "title": "Node básico" }, la respuesta 201 con id y title, y el error 400 con VALIDATION. Añade 404 solo si esa operación puede referir otro recurso.
Fixture GET: curso7={id:7,title:"Node básico"}, curso99 ausente. Documenta200 con ese objeto y404 con {ok:false,error:{code:"NOT_FOUND"}}; añade400 para parámetro no numérico si ese contrato existe. Si publicas OpenAPI, declarar respuestas allí no implementa validación ni auth: ejecuta los casos contra tu entorno local y comprueba schema/código de estado. Mantén documentación privada de secretos fuera de ejemplos públicos.
Pruébalo
Elige un endpoint que exista en tu aplicación.
Copia una solicitud válida y una inválida reales.
Anota código HTTP, forma JSON y condiciones que producen cada respuesta.
Error frecuente: documentar nombres intuitivos que no implementa la ruta. Corrige ejecutando cada ejemplo y ajustando el contrato a la salida observada, o cambia el código deliberadamente y vuelve a probarlo.
Ejercicio: documenta GET /courses/:id con los casos 200 y 404.
Comprueba tu resultado
otra persona puede construir ambas solicitudes, conoce la forma de una respuesta válida y puede identificar el código NOT_FOUND sin leer el controlador.
Mapa de prácticaEl navegador envía una solicitud a la API. El servidor valida la operación y consulta los datos; después devuelve una respuesta que el navegador puede mostrar. La base de datos se comunica con el servidor y no directamente con el navegador.
Ver la infografía en tamaño completo ↗Documentacion
Una API sin docs es soporte infinito. Documenta endpoints, inputs, outputs y errores.
Conceptos clave
- OpenAPI (idea)
- Ejemplos reales de request/response
- Errores documentados
Ejemplo
Documenta al menos: POST /signup, GET /me, GET /items.
Ejercicio
- Escribe docs de 1 endpoint con ejemplos.
- Incluye 2 casos de error.
Checklist de mastery
- Mis endpoints tienen ejemplos.
- Los errores estan documentados.
Sigue con Node.js y APIs con Express
Esta lección forma parte de un curso de Cursalo. Revisa su programa y elige entre la compra individual o el acceso a toda la escuela.
Si ya tenías acceso a este curso, entra con tu cuenta: tus derechos y tu progreso se conservan. No necesitas comprarlo de nuevo.