El contrato de la v1 de Tienda Aroma está completo: recursos, URIs, métodos, códigos, representaciones, colecciones y una política de versionado. Pero un contrato que solo existe en la cabeza del equipo que lo diseñó no es un contrato: es un acuerdo tácito esperando a ser incumplido. Esta lección trata la pieza que convierte el diseño en algo utilizable por otros. Veremos por qué la documentación es parte del producto y no un extra, qué tipos de documento sirven a qué lector, qué debe incluir la referencia de cada endpoint, y qué cambia radicalmente cuando el contrato se escribe en un formato legible por máquinas como OpenAPI. Cerramos el módulo 2 haciendo balance de todo el contrato diseñado y preparando el salto al módulo 3.

1. La documentación es parte del producto
2. Tipos de documentación y a quién sirve cada uno
3. Anatomía de la referencia de un endpoint
4. Documentación dirigida por contrato: OpenAPI
5. Un fragmento real: GET /cafes en OpenAPI
6. Qué desbloquea una especificación legible por máquinas
7. Documentación como código
8. Buenas prácticas de redacción
9. Mantener la documentación viva
10. Balance del contrato de Tienda Aroma

Una API no tiene interfaz visual. No hay botones que explorar ni menús que insinúen lo que se puede hacer. Para un desarrollador que la consume, la documentación es literalmente el producto: si no está documentado, no existe.

Piénsalo desde el otro lado. Cuando el equipo de RápidoEnvíos se sienta a integrar Tienda Aroma, su experiencia consiste en: leer, probar un curl, leer otra vez, escribir código, encontrar un error no documentado, escribir un correo, esperar dos días. Cada uno de esos pasos es coste. Lo que la buena documentación reduce no es "molestias": es tiempo hasta la primera llamada correcta, la métrica que decide si tu API se adopta o se abandona.

Consecuencias prácticas de tomárselo en serio:

• Se planifica y se estima como cualquier otra funcionalidad. Un endpoint sin documentar no está terminado.
• Se prueba: los ejemplos se ejecutan, no se copian de memoria.
• Tiene responsable y se revisa en las pull requests.
• Reduce el soporte: cada pregunta que llega por correo es una pregunta que la documentación no respondió, y la respuesta correcta no es contestar el correo, sino arreglar la documentación.

El error más común es escribir un único documento gigante. Hay lectores distintos, en momentos distintos, con necesidades incompatibles.

El objetivo es una sola cosa: una llamada correcta en menos de cinco minutos. Nada de arquitectura, nada de teoría.

curl -H "Authorization: Bearer TU_TOKEN"
"https://api.tiendaaroma.example/v1/cafes?limite=3"

{ "datos": [ { "id": "caf_001", "nombre": "Etiopía Yirgacheffe", "precioEuros": 14.50 } ], "total": 137 }

Explica el modelo mental, que ninguna referencia transmite. Para Tienda Aroma: qué es un carrito y en qué se diferencia de un pedido, la máquina de estados de los pedidos, el ciclo de moderación de reseñas, cómo funcionan los webhooks firmados, qué significa que los identificadores sean opacos. Sin esto, el integrador deduce el modelo por prueba y error, y deduce mal.

Recorren un caso de uso completo de principio a fin: "Del carrito al pedido pagado", con las siete llamadas encadenadas, sus respuestas reales y los errores probables en cada paso. Es lo que más se agradece y lo que menos se escribe.

Una entrada por cambio, con fecha, tipo (añadido / cambiado / deprecado / eliminado / corregido) y enlace a la guía de migración cuando toque:

Es el documento más barato de mantener y el que más confianza genera: demuestra que la API está viva y que los cambios se anuncian.

La referencia es lo que se consulta a diario. Cada endpoint necesita todos estos elementos; si falta uno, alguien acabará preguntándolo por correo.

Ejemplo abreviado de cómo queda para Tienda Aroma:

curl -i -X POST "https://api.tiendaaroma.example/v1/pedidos/ped_5001/pago"
-H "Authorization: Bearer $AROMA_TOKEN"
-H "Idempotency-Key: 5f3b9c2a-1d7e-4a44-9f30-8b1c2d3e4f50"
-H "Content-Type: application/json"
-d '{ "metodo": "tarjeta", "tokenTarjeta": "tok_visa_4242" }'

La columna de errores es la que más se omite y la que más incidencias evita: sin ella, el integrador descubre el 409 el día que un usuario pulsa dos veces.

Todo lo anterior se puede escribir a mano en Markdown. Funciona, y para una API pequeña puede bastar. Pero hay una alternativa que cambia las reglas del juego: escribir el contrato en un formato que las máquinas entiendan.

OpenAPI (antes Swagger) es una especificación —hoy en su versión 3.1— para describir una API HTTP en YAML o JSON: sus rutas, métodos, parámetros, esquemas de datos, respuestas, errores y seguridad. No es documentación sobre la API: es la API descrita formalmente, y la documentación legible es solo uno de sus productos.

La diferencia con la documentación escrita a mano es de naturaleza, no de grado: un documento en Markdown describe el contrato y puede mentir; una especificación OpenAPI es el contrato y se puede verificar contra la implementación de forma automática.

Esta lección se queda en el porqué y en un fragmento ilustrativo. Swagger y OpenAPI a fondo —editores, generadores, interfaz interactiva, buenas prácticas de escritura— son la lección 05-02, y el uso del contrato para mocks y pruebas automatizadas es 05-04.

Este es el aspecto que tiene el contrato de la colección de cafés que diseñamos en 02-06, escrito en OpenAPI 3.1:

Fíjate en cuánto contrato de este módulo está aquí codificado, y de forma verificable:

• El limite por defecto 20 y máximo 100, y el tope de desplazamiento (02-06).
• El desempate por id en la ordenación, documentado en la descripción.
• El envoltorio datos/total (02-05) y el formato de error con codigo/mensaje/detalles (02-04).
• El patrón del identificador y el aviso de opacidad (02-02).
• Los importes con multipleOf: 0.01, es decir, dos decimales (02-05).
• El aviso de que el enumerado tueste puede crecer (02-07).
• La cabecera Link como parte declarada de la respuesta.

Los $ref a components evitan repetir limite, desplazamiento, Cafe y Error en cada endpoint: se escriben una vez y se referencian, que es exactamente la consistencia que pedía 02-01, ahora garantizada por construcción.

El más importante para un proyecto API-first como el nuestro es el mock: con el openapi.yaml terminado, la SPA y Aroma Móvil pueden empezar a integrar el día uno contra un servidor simulado, mientras el equipo de servidor implementa. Eso es lo que hace que "diseñar antes de programar" no sea tiempo perdido, sino paralelismo ganado.

La documentación se trata exactamente igual que el código:

• Vive en el repositorio, junto a la implementación. openapi.yaml en la raíz, guías en docs/.
• Se versiona con Git, así que el histórico responde a "¿desde cuándo dice esto?".
• Se revisa en pull request: un cambio de API que no toca el contrato ni el changelog no se aprueba.
• Se valida en integración continua: la especificación se comprueba sintácticamente, se pasa un linter de estilo y se ejecutan las pruebas de contrato.
• Se publica automáticamente al fusionar en la rama principal.

Estructura típica del repositorio de Tienda Aroma:

El detalle que hace que esto funcione de verdad: la puerta de calidad en CI. Si el pipeline falla cuando la implementación no cumple el contrato, la documentación deja de depender de la buena voluntad. Se monta en 05-05.

Ejemplos reales y copiables. Nada de <TU_ID_AQUÍ> mezclado con datos falsos. Usa los identificadores del dominio (caf_001, ped_5001, cli_842) de forma consistente en toda la documentación: quien lee un tutorial reconoce los mismos datos en la referencia.

curl completo, siempre. Con la cabecera de autenticación, la URL entrecomillada (por el &, como vimos en 01-03) y el cuerpo entero. Es el mínimo común denominador: funciona en cualquier sistema y no supone ningún lenguaje.

Documenta los errores tanto como los éxitos. Es la diferencia más visible entre una documentación profesional y una amateur.

Explica el porqué, no solo el qué. "Idempotency-Key es obligatoria porque un reintento tras un timeout podría cobrar dos veces" enseña; "Idempotency-Key: cadena, obligatoria" solo informa.

Nada de "TBD", "por documentar" o "pendiente". Un hueco declarado es peor que la ausencia: el lector pierde el tiempo confiando en que aparecerá.

Coherencia con la guía de estilo. Si la guía dice camelCase, ningún ejemplo lleva snake_case. La documentación es donde las incoherencias se ven, y donde destruyen la confianza más rápido.

Escribe para quien no conoce tu dominio. El primer uso de "carrito", "línea" o "moderación" merece una definición. El equipo de RápidoEnvíos sabe de logística, no de café de especialidad.

Cuidado con las capturas de pantalla. Envejecen mal y no se pueden buscar ni copiar. Prefiere bloques de código.

El enemigo tiene nombre: la deriva (drift), la distancia que se abre entre lo que la documentación dice y lo que la API hace. Una API mal documentada es un problema; una API mal documentada que parece bien documentada es peor, porque el integrador confía y falla.

Tienda Aroma usa el enfoque mixto: openapi.yaml escrito a mano —es la fuente de verdad, coherente con el API-first de 02-01— y pruebas de contrato en CI que fallan si la implementación se desvía. Las guías y tutoriales se escriben a mano siempre: ningún generador explica por qué un carrito no es un pedido.

• El changelog lleva meses sin entradas, pero la API ha cambiado.
• Los ejemplos usan campos que ya no existen.
• Hay endpoints en producción que no aparecen en la especificación.
• Las respuestas de error reales no coinciden con las documentadas.
• El equipo responde por chat preguntas que la documentación debería responder.

Esto es lo que hemos diseñado a lo largo del módulo 2, y es exactamente lo que el módulo 3 va a implementar.

Método y principios (02-01). Enfoque API-first, consumidores identificados (SPA, Aroma Móvil, panel interno, RápidoEnvíos), recursos extraídos del dominio y una guía de estilo escrita.

Recursos y URIs (02-02). Mapa completo de 24 URIs sobre https://api.tiendaaroma.example/v1, plural en minúsculas, kebab-case, anidamiento máximo de dos niveles, singleton en singular, identificadores opacos con prefijo y acciones no CRUD modeladas como subrecursos con POST (/pago, /anulacion, /aprobacion, /rechazo).

Métodos (02-03). GET, POST, PUT, PATCH, DELETE, HEAD y OPTIONS asignados recurso a recurso; PATCH con JSON Merge Patch; borrado lógico invisible desde fuera; Idempotency-Key obligatoria en POST /pedidos y POST /pedidos/{id}/pago.

Códigos (02-04). Los códigos que se usan de verdad, con 201 + Location, 409 para los conflictos de estado, la distinción 401/403 y 404/410; formato de error propio {"error": {"codigo", "mensaje", "detalles"}} frente a problem+json; catálogo de 28 códigos de error de negocio.

Representaciones (02-05). camelCase, ISO-8601 UTC, euros con dos decimales, enumerados snake_case ampliables, null frente a ausente, envoltorio datos/total, criterios de incrustar frente a enlazar, _links de hipermedia selectiva, expandir y campos, y negociación con Accept, Accept-Language, Accept-Encoding y Vary.

Colecciones (02-06). Filtros explícitos, rangos Min/Max y Desde/Hasta, multivalor con comas, ordenar con desempate por id, offset para /cafes y cursor para /pedidos, total en el cuerpo y navegación en la cabecera Link, ?q= para búsqueda, y límites por defecto y máximos.

Evolución (02-07). Versión en la ruta, dos versiones vivas como máximo, 12 meses de deprecación, cabeceras Deprecation y Sunset y apagado con 410 Gone.

Documentación (02-08). openapi.yaml como fuente de verdad, guías y tutoriales a mano, changelog por fecha, todo en el repositorio y validado en CI.

• Dejar la documentación para el final. Nunca llega ese final. Documenta el endpoint en la misma pull request que lo crea.
• Documentar solo el camino feliz. Los errores son la mitad del trabajo del integrador: 409 y 422 sin documentar generan incidencias que nadie sabe explicar.
• Ejemplos que no se pueden ejecutar. Prueba cada curl de la documentación. Si un ejemplo falla, has perdido la confianza del lector para todo lo demás.
• Confundir referencia con guía. La referencia dice qué acepta un endpoint; nunca explica cómo encadenar seis llamadas para pagar un pedido. Hacen falta las dos.
• Generar la documentación del código y darla por buena. Documenta lo que hay, incluidos los bugs, y no dice nada de conceptos ni de intención.
• No documentar los límites. Rate limits, tamaños máximos, limite máximo y profundidad de expansión son parte del contrato: sin ellos, el integrador los descubre con un 400 en producción.
• Olvidar el changelog. Es el documento más barato y el que más agradece un consumidor externo.
• Consejo: mide el "tiempo hasta la primera llamada correcta". Siéntate con alguien que no conozca la API, dale la documentación y cronometra en silencio. Descubrirás más en veinte minutos que en tres reuniones.
• Consejo: trata cada pregunta de soporte como un fallo de documentación. La respuesta no es contestar el correo, es arreglar el documento y luego contestar con el enlace.

Escribe la documentación de referencia completa de POST /v1/cafes/{cafeId}/resenas con todos los elementos de la sección 3. Usa el contrato diseñado en este módulo: el cuerpo lleva puntuacion (entero de 1 a 5) y comentario (texto de hasta 5.000 caracteres); la reseña se crea en estado pendiente_moderacion; solo pueden reseñar los clientes que hayan comprado ese café.

Amplía el fragmento de la sección 5 añadiendo la operación GET /cafes/{cafeId}: parámetro de ruta, respuesta 200 con el esquema Cafe reutilizado, respuesta 404 con el esquema Error y ejemplo del error cafe_no_encontrado, y respuesta 304 para la caché condicional. Reutiliza los components existentes.

Un desarrollador llega a Tienda Aroma y encuentra esto. Identifica todos los problemas de documentación y propón el remedio concreto y el proceso que evitaría que vuelva a ocurrir.

• La referencia dice que GET /v1/cafes devuelve un array; la API devuelve {"datos": [...], "total": n}.
• No hay ninguna mención al parámetro expandir, que sin embargo funciona.
• El ejemplo de POST /v1/pedidos no incluye la cabecera Idempotency-Key, que es obligatoria.
• La tabla de errores de POST /v1/pedidos/{id}/pago solo lista 400 y 500.
• El changelog termina hace ocho meses.
• Hay un endpoint /v1/promociones en producción que no aparece en ningún sitio.

Solución 1

curl -i -X POST "https://api.tiendaaroma.example/v1/cafes/caf_001/resenas"
-H "Authorization: Bearer $AROMA_TOKEN"
-H "Content-Type: application/json"
-d '{ "puntuacion": 5, "comentario": "Cítrico y floral, espectacular en V60." }'

HTTP/1.1 201 Created Location: https://api.tiendaaroma.example/v1/resenas/res_101

{ "id": "res_101", "cafeId": "caf_001", "clienteId": "cli_842", "puntuacion": 5, "comentario": "Cítrico y floral, espectacular en V60.", "estado": "pendiente_moderacion", "fechaCreacion": "2026-03-14T10:30:00Z", "_links": { "self": { "href": "/v1/resenas/res_101" }, "cafe": { "href": "/v1/cafes/caf_001" } } }

Observa que ha aparecido un código de error nuevo, resena_duplicada (409): documentar obliga a cerrar decisiones que el diseño había dejado abiertas. Ese es uno de los grandes beneficios de escribir la referencia antes de implementar.

Solución 2

Nótese que Cafe y Error se reutilizan con $ref: al añadir mañana un campo al esquema Cafe, aparece automáticamente en las dos operaciones y en la documentación generada. Eso es consistencia garantizada por construcción, no por revisión humana.

Solución 3

El proceso que lo evita todo, en una frase: la especificación es la fuente de verdad, vive en el repositorio, se valida en cada pull request y el pipeline falla si la implementación no la cumple. Sin puerta automática, la deriva es cuestión de tiempo.

La documentación no es lo que se escribe después de programar: es la cara visible de un producto que no tiene interfaz. Ahora sabes que hacen falta documentos distintos para lectores distintos —inicio rápido, conceptos, tutoriales, referencia, changelog—, qué debe contener la referencia de cada endpoint (incluidos todos sus errores, que es lo que más se omite), y por qué escribir el contrato en OpenAPI cambia la naturaleza del asunto: deja de ser un texto que describe la API y pasa a ser el contrato mismo, del que salen la documentación navegable, los clientes, los mocks, las pruebas y la configuración del gateway. Con documentación como código, revisada en pull request y validada en CI, la deriva deja de depender de la buena voluntad.

Con esto cerramos el módulo 2. Has diseñado, pieza a pieza y sobre el papel, el contrato completo de la API de Tienda Aroma: su método de trabajo y su guía de estilo, sus 24 URIs con las acciones modeladas como subrecursos, sus métodos con la idempotencia del pago resuelta, su tabla de códigos y su catálogo de errores de negocio, sus representaciones con hipermedia selectiva, sus colecciones filtradas y paginadas, su política de versionado y deprecación, y su documentación. Nada de esto ha necesitado todavía una línea de servidor, y esa era exactamente la idea: en API-first, el contrato va delante. Ahora toca cumplirlo. En el módulo 3, Desarrollo de APIs RESTful, montaremos el entorno con Node.js 20, levantaremos el servidor con Express y convertiremos cada decisión de este módulo en código: las rutas del mapa de URIs, la validación que devuelve datos_invalidos con sus detalles, la capa de persistencia que traduce céntimos a euros, la autenticación que distingue 401 de 403, el middleware de errores que emite el formato que hemos fijado y las pruebas que verifican que la implementación respeta el contrato. Empezamos por el principio: 03-01, Configuración del entorno de desarrollo.