Documentar una API interna para el yo del futuro
Introducción breve
Volver a un endpoint meses después me sale más barato si dejé escrito qué prometía al resto del sistema, no solo cómo está implementado.
Problema o decisión
Las APIs internas crecen por iteraciones; el consumidor es otro servicio o un script que uno mismo olvida. Sin texto mínimo, cada cambio de contrato es adivinanza y cada baja del equipo es pérdida de contexto. El problema no es “falta de manual”, sino ausencia de contrato legible frente al tiempo.
Qué hice o cómo lo planteé
Para cada recurso que otros consumen, dejo al menos: alcance en una frase (qué hace y qué queda fuera); contrato (método, ruta, cuerpo, respuesta, fechas/nulos); errores estables y qué puede hacer el cliente ante cada uno; un ejemplo request/response copiable con datos ficticios. Evito PDF estático que envejece el primer día, la firma Java sin mapear al HTTP, y documentar “como debería ser” si producción se comporta distinto.
Qué aprendí
Lo que más retorno da suele caber en una pantalla por endpoint. El coste marginal baja cuando el patrón ya está en el repo o en la wiki del equipo: menos reuniones para reconstruir el contrato.
Proyecto relacionado
El caso Backend Java y APIs internas es donde encaja esta línea de trabajo con servicios y contratos en JVM.