Changelog de API: qué publicar y quién lo lee

Un changelog de API es el registro fechado de cada cambio que un consumidor podría notar, escrito para quienes integran contra la API, no para el equipo que la publica. Ese público lo convierte en un documento distinto de un changelog de producto: el lector está decidiendo si su código seguirá funcionando el próximo mes. La mayoría fallan del mismo modo, siendo una copia filtrada de un feed interno de releases, así que un campo eliminado queda junto a un ajuste de texto con el mismo peso y ninguno de los dos se lee.

¿Qué es un changelog de API?

Es el registro público y fechado de cambios en una interfaz contra la que otras personas han escrito código. La prueba útil para decidir si algo pertenece ahí no tiene nada que ver con cuán grande fue el cambio internamente. Pregunta si un consumidor correcto, escrito el año pasado y sin tocar desde entonces, podría comportarse de forma distinta por ello. Esa prueba admite algunos cambios muy pequeños y excluye algunos muy grandes.

Todo lo que sigue asume que quien llama está fuera de la empresa y es efectivamente inalcanzable salvo a través de este documento. Cuando quien llama es otro equipo dentro de la misma empresa, el cálculo cambia lo suficiente como para necesitar un tratamiento propio; changelogs de API interna cubre lo que ese público necesita en su lugar.

Cómo escribir una guía de migración de API cubre ese último documento por completo; en resumen es lo que una entrada de cambio incompatible debería enlazar en vez de intentar reemplazar.

Los cinco son documentos separados con ciclos de vida separados. Un aviso de depreciación es una promesa con fecha y también pertenece al changelog, pero una entrada de changelog se escribe una vez mientras que una depreciación se sigue hasta su sunset. Colapsarlos es la razón por la que los sunsets se pasan por alto.

¿Qué pertenece a una sola entrada?

Seis cosas, y las tres primeras son las que suelen faltar. El cambio, expresado en términos de la petición o la respuesta en lugar del componente interno. Si rompe a un consumidor correcto. Qué tiene que hacer el consumidor, incluido “nada”. La fecha en que tomó efecto. La versión o versiones afectadas. Un enlace a la guía de migración cuando existe.

Una entrada que dice “mejorado el endpoint de cuentas” falla en las seis. Una entrada que dice “el campo accounts.type ahora devuelve individual donde antes devolvía personal; los valores existentes no cambian para cuentas creadas antes del 2 de septiembre; no se requiere acción salvo que compares el string” responde las seis en una frase.

Categoriza las entradas por consecuencia, no por departamento. Tres etiquetas cargan casi todo el valor: breaking, additive y fixed. Semantic Versioning ya define las dos primeras con precisión, y tomar prestadas sus definiciones en lugar de inventar otras propias significa que un lector que conoce semver conoce tus etiquetas. Keep a Changelog ofrece un conjunto más largo si lo quieres, y su regla central se aplica aquí con más fuerza que en ningún otro sitio: el log es para humanos, y un volcado de títulos de commit no lo es.

¿En qué se diferencia un changelog de API de las notas de versión?

Las notas de versión describen qué puede hacer ahora el producto. Un changelog de API describe cuál es ahora el contrato. El mismo trabajo publicado suele producir una entrada en ambos, redactada de forma distinta, porque los públicos necesitan cosas distintas: un nuevo formato de exportación es una función para un usuario y un nuevo valor de enum para un consumidor que depende de ese campo.

La consecuencia práctica es que los dos no pueden ser el mismo feed con distinto estilo. Un consumidor que se suscribe a todo lo que publicas acabará dándose de baja, y entonces se perderá el breaking change. Si publicas un feed, fíltralo; si publicas dos, haz el de API más estrecho y nunca dejes entrar una entrada de marketing. Comparamos ambas formas lado a lado en changelog vs notas de versión.

¿Dónde debería vivir un changelog de API?

Junto a la documentación de referencia, en una URL estable, con cada entrada direccionable por separado mediante un fragmento o su propia ruta. Los consumidores enlazan entradas en revisiones de incidentes y tickets internos, y una entrada que no se puede enlazar acaba pegada como captura de pantalla en su lugar.

Publícalo también como salida legible por máquina, además de como página. Un feed JSON siguiendo la especificación JSON Feed o un feed RSS no cuesta nada una vez que las entradas son datos estructurados, y es lo que permite a un cliente incorporar tus cambios a su propio proceso de release. Esto también decide si alguien construye sobre ello. GitHub documenta sus versiones de la REST API junto a la referencia por la misma razón: la política de versiones es parte de la interfaz.

¿Cómo es una buena entrada en la práctica?

Tres entradas de la misma semana, con la forma descrita arriba:

2026-09-02  Breaking  v2
  `POST /invoices` ahora rechaza una `currency` que no coincide con la
  moneda de cuenta del cliente, devolviendo 422 en lugar de convertir en
  silencio. Los consumidores que dependían de la conversión deben enviar
  la moneda de cuenta. Afecta solo a v2; v1 no cambia hasta su sunset el
  2027-01-15.

2026-09-02  Additive  v1, v2
  `Invoice` gana un timestamp `settled_at`, null hasta que la factura se
  liquida. No se requiere acción. Los clientes que rechazan campos
  desconocidos deberían actualizarse.

2026-08-31  Fixed  v2
  `GET /invoices?status=` devolvía una página vacía en lugar de un 400
  ante un estado desconocido. Ahora devuelve 400 con los valores
  aceptados. Los consumidores con una errata antes veían cero resultados
  y ahora ven un error.

La tercera es el tipo que más se suele omitir, porque internamente es una corrección de bug. Para un consumidor que construyó un retry alrededor de esa página vacía, es un cambio de comportamiento, y la entrada es lo que evita el ticket de soporte. La etiqueta dice fixed y el cuerpo dice qué podría notar un consumidor, que es la distinción que mantiene el log honesto sin inflar cada corrección a breaking change.

¿Cómo se suscriben los consumidores?

Dales más de un canal, porque tienen trabajos distintos. Un feed para el desarrollador que lo quiere todo. Correo para quien solo quiere breaking changes. Cabeceras de respuesta para el propio código, el único suscriptor que nunca olvida comprobar: la cabecera Sunset definida en RFC 8594 pone la fecha de retiro en la respuesta, donde una librería cliente puede registrarla.

El canal que más equipos se saltan es el directo. Si un consumidor usó el campo que estás cambiando la semana pasada, sabes quién es, y un correo a esas cuentas vale más que cualquier cantidad de difusión general. Es la misma disciplina que cerrar el bucle de feedback del cliente, aplicada a un cambio que nadie pidió: a los afectados se les avisa individualmente, y al resto le llega el feed. Un webhook es un cuarto canal con su propio modo de fallo que conviene conocer antes de confiar en él: changelogs de webhooks cubre por qué un cambio de payload ahí rompe en silencio, sin consumidor que pueda rechazar la nueva forma.

¿Cómo se escribe una entrada para un breaking change?

Empieza por la ruptura, no por la razón. Un consumidor que revisa diez entradas necesita saber en la primera frase si esta le va a costar trabajo. Después la fecha, las versiones afectadas, la migración, y el plazo si el comportamiento antiguo va a desaparecer en lugar de cambiar.

Pon el mismo contenido en el aviso de depreciación, la cabecera de respuesta y el correo directo, redactado de forma consistente, y dales a los cuatro la misma fecha. La discrepancia entre ellos es el fallo que convierte un cambio planeado en un incidente, porque el consumidor que solo leyó uno actúa según la fecha equivocada. Qué es un breaking change cubre la decisión en sí, y cómo deprecar una API cubre el calendario que sigue.

En changeloop, un cambio de API se convierte en una entrada cuando se fusiona el pull request, una persona edita y aprueba el borrador, y la entrada se publica en el feed y el widget en el mismo momento en que se avisa, en ese issue, al consumidor cuyo feedback en el widget se convirtió en el issue de GitHub que cierra el pull request. El paso de revisión es lo que importa aquí: un changelog de API es un documento contractual, y ningún borrador debería llegar a un consumidor sin que una persona lo haya leído.

FAQ

¿Toda cambio de API necesita una entrada de changelog? Todo cambio que un consumidor correcto pudiera notar, sí, incluidos los que consideres internos. Los cambios sin efecto observable en la petición o la respuesta no, y añadirlos entrena a los lectores a pasar por encima.

¿El changelog de API debería vivir en los docs o en el sitio de marketing? En los docs, junto a la referencia. El lector suele estar ya ahí, y un changelog en el sitio de marketing tiende a ganar un público para el que no fue escrito.

¿Hasta cuándo debería remontarse? Indefinidamente. Las entradas se citan años después en revisiones de incidentes, y un log truncado rompe esos enlaces. Pagina en lugar de podar.

¿Necesito un changelog separado por versión de API? No, un único log con un campo de versión por entrada es más fácil de leer y de buscar. Filtrar por versión es una función de la página, no una razón para dividir el documento.

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, Ejemplos de changelog