Changelogs de API internas: qué cambia para el otro equipo

Cada otro artículo de este hub asume que quien llama a una API está fuera de la empresa: la ingeniera de una clienta, una socia, alguien que encontró la documentación por su cuenta. Muchas APIs tienen un tipo de consumidor totalmente distinto, un equipo al otro lado del pasillo o a dos pisos de distancia, y eso cambia el cálculo de qué le debe un changelog, porque un mensaje de Slack lo alcanza y normalmente nunca se abre un ticket de soporte. La mayoría de los equipos concluye de esto que las APIs internas no necesitan changelog. Lo que realmente necesitan es uno distinto.

¿Qué hace diferente al changelog de una API interna del de una pública?

El público es alcanzable directamente, lo que elimina la razón principal por la que existen la mayoría de los changelogs de API públicos: transmitir a consumidores a los que no se puede contactar individualmente. El equipo dueño de una API interna suele saber exactamente qué otros equipos la llaman, a veces hasta el servicio específico. Eso hace que un mensaje dirigido, no un feed público, sea el valor predeterminado natural, y por eso las APIs internas tan a menudo terminan sin ningún changelog: el equipo dueño le avisa a los dos o tres equipos que recuerda, asumiendo que eso cubre a todos.

¿Por qué falla “simplemente le avisamos a los equipos que nos llaman”?

Porque el conjunto de consumidores nunca es tan pequeño ni tan estático como recuerda el equipo dueño. Un servicio construido para un consumidor gana un segundo seis meses después, mediante una integración que nadie anunció, y la lista mental de “quién nos llama” del equipo dueño ya está equivocada sin que nadie lo note. El fallo es ordinario y común, el resultado predeterminado de confiar en la memoria en vez de en un registro, no una señal de que alguien fue descuidado. Qué es un breaking change cubre cómo decidir si un cambio de API cuenta como rompedor en primer lugar; el caso interno añade una segunda pregunta más difícil encima de esa, que es saber a quién avisar.

¿Una API interna necesita siquiera una página de changelog al estilo público?

Casi siempre sí, aunque el canal principal sea directo. Una página le da al mensaje directo algo a qué enlazar, así que la notificación puede ser corta (“breaking change en /v2/accounts, detalles aquí”) en lugar de intentar llevar toda la explicación en un mensaje de chat que va a desaparecer al hacer scroll. También se convierte en lo que un equipo nuevo, o uno que se perdió el mensaje directo, puede revisar cuando su integración se rompe y trata de entender por qué. La página no necesita estar pulida ni ser pública; necesita ser enlazable y sobrevivir al hilo de Slack que la anunció.

¿Quién mantiene realmente la lista de consumidores?

El equipo dueño, y hay que tratarla como un artefacto real, no como conocimiento tribal. La versión más barata es un archivo en el propio repositorio de la API, una lista corta de servicios consumidores con una responsable por entrada, actualizada cada vez que se construye una nueva integración, la misma disciplina que cualquier declaración de dependencias. La alternativa, preguntar por ahí antes de cada breaking change, funciona hasta el día en que alguien se olvida de preguntarle a la persona correcta, y una API interna que se rompe en silencio para un equipo es un incidente más pequeño que uno público, pero sigue siendo un incidente, normalmente descubierto por la guardia de ese propio equipo en vez de por quien es dueña de la API.

# consumers.yml
- service: billing-service
  owner: "#team-billing"
  since: 2026-03-01
- service: reporting-pipeline
  owner: "#team-analytics"
  since: 2026-06-14

Un archivo así convierte “a quién tenemos que avisar” en una consulta en lugar de una pregunta. Herramientas construidas exactamente para este problema, como el catálogo de servicios de Backstage, modelan las APIs como entidades de primera clase con consumidores declarados por la misma razón: en cuanto una organización tiene suficientes servicios internos, la memoria de nadie sobre quién llama a qué se mantiene precisa por sí sola, y algo tiene que guardar el registro en su lugar. La documentación de la herramienta que ya uses internamente suele ser el sitio correcto donde mirar antes de construir una a medida.

¿Qué pertenece a una entrada de changelog interna que una pública no necesitaría?

Más especificidad operativa, porque quien lee es otra ingeniera que va a actuar sobre esto dentro de la misma infraestructura, no a leerlo como un resumen. En qué entornos está viva la modificación y cuándo, porque los servicios internos a menudo se promueven por etapas que un consumidor público nunca ve. Si el cambio requiere una actualización de configuración o de biblioteca cliente del lado del consumidor, formulada como un comando si existe uno. Y, porque los consumidores internos suelen poder coordinar la solución directamente con el equipo dueño, un contacto con nombre en lugar de un canal de soporte: “avisa a @maria si esto rompe algo” es una línea perfectamente razonable en una entrada interna y una extraña en un changelog de API pública.

¿Esto aplica igual a un changelog dentro de un monorepo?

Agudiza el mismo problema en lugar de reemplazarlo. Changelogs de monorepo cubre cuándo un paquete necesita su propio changelog; una API interna que es uno de varios paquetes en un monorepo igual necesita que sus consumidores estén rastreados explícitamente, porque estar en el mismo repositorio que quienes la llaman no significa que vayan a notar un cambio a menos que algo les diga que miren. La cercanía en el repo no es lo mismo que la cercanía en la atención.

FAQ

¿Una API solo interna necesita changelog si tiene un único consumidor? Apenas, y un mensaje directo a ese único equipo suele bastar. El changelog se justifica en cuanto hay más de un consumidor, o en cuanto la lista de consumidores ha sorprendido alguna vez al equipo dueño, porque esa es la señal de que la memoria sola ya no es confiable.

¿Los cambios de API internos deberían pasar por la misma revisión que los públicos? La redacción puede ser más ligera, porque quien lee es una colega y no una consumidora externa, pero la decisión de si un cambio es rompedor merece el mismo cuidado en ambos casos. Una consumidora interna igual tiene código en producción que depende del comportamiento anterior.

¿Cómo se averigua quién llama a una API interna si nunca se registró? Los logs del servidor o los datos de tráfico de un service mesh son la respuesta honesta si nunca se mantuvo un registro de consumidores; trata ese descubrimiento como el momento de empezar uno, no como una limpieza puntual.

¿Un mensaje de Slack basta, o un cambio interno igual necesita una entrada formal de changelog? Ambos, para cualquier cosa que no sea puramente aditiva. El mensaje es lo que se lee a tiempo; la entrada es lo que un equipo investigando un problema semanas después, que nunca vio el mensaje, puede encontrar de todos modos.

Las afirmaciones técnicas de este artículo no se han revisado de forma independiente. Si algo está mal, avísanos y lo corregiremos.

Relacionado en changeloop: Documentación para desarrolladores, Herramientas de changelog comparadas