La referencia dice lo que la API es. El registro de cambios dice cómo llegó a serlo, y es lo primero que lee un consumidor cuando algo que ayer funcionaba hoy no funciona.
## 2027-03-01
- Obsoleta: la versión v1. Deja de responder el 2027-09-01.
Consulta la guía de migración.
## 2027-02-10
- Añadido: `status` en el objeto licencia (solo v2).
- Añadido: se acepta `Idempotency-Key` en POST /licenses.
Cada entrada tiene una fecha. Un consumidor siempre está preguntando «¿qué cambió desde el martes pasado?».
Las entradas se escriben para el consumidor. «Se refactorizó el driver» no es una entrada de registro de cambios. Para él no cambió nada. «Los timeouts del proveedor ahora devuelven 504 con un código» sí lo es.
Los añadidos también se listan. Un registro de cambios que solo anota roturas le enseña a la gente que cada entrada es una mala noticia.
Escribe la entrada en el pull request que hace el cambio. Es el mismo hábito que las notas de documentación del Capítulo 14: la única actualización que sobrevive con seguridad es la que viaja con el código.
Protege la documentación, o no
Decide quién puede leer la referencia de tu API.
Para una API pública, la documentación es marketing y debería estar abierta. Para una interna, como la License API, la referencia describe cada endpoint de un sistema que gestiona credenciales, y no hay razón para que sea legible desde internet. Ponla detrás del mismo tipo de comprobación que la API, y recuerda que el documento OpenAPI revela tanto como las páginas que se generan a partir de él.
Lo que nunca debería estar en ninguno de los dos: un token real en un ejemplo, el nombre de un consumidor real, un nombre de host de algo interno. Los ejemplos se copian. Da por hecho que lo que haya en un ejemplo lo pegará alguien, en algún sitio, en una terminal.
Resumen del capítulo 15
- Empieza con una llamada que funcione. El primer minuto de un consumidor decide si el resto se lee.
- Describe la API en OpenAPI, y genera esa descripción a partir de los FormRequests, los Resources y las rutas.
- Un generador solo puede leer lo que está declarado. Quedarse dentro del framework es lo que hace que la API se pueda describir.
- Escribe tú el significado: para qué sirve cada endpoint, y las guías.
- Sube al repositorio el documento generado. Haz fallar el build cuando esté desactualizado, y cuando un cambio sea incompatible.
- Documenta cada error con lo que el consumidor debe hacer a continuación.
- Lleva un registro de cambios con fechas, escrito para los consumidores, actualizado en el pull request que hace el cambio.
- Decide quién puede leer la documentación, y deja los secretos y los nombres reales fuera de los ejemplos.