Cómo escribir una guía de migración de API

Una guía de migración de API es el documento que convierte un cambio incompatible en una checklist en lugar de una caída: qué cambió, qué hacer al respecto, y para cuándo. Una entrada de changelog puede nombrar un cambio incompatible en dos frases; una guía de migración es lo que quien llama abre realmente cuando esas dos frases dicen “esto te rompe” y necesita saber exactamente qué editar. Publicar la entrada sin la guía es cómo quien llama se entera de un cambio incompatible por un ticket de soporte en vez de por el documento escrito para evitarlo.

¿Qué es una guía de migración de API?

Un documento paso a paso que lleva a quien llama desde la forma antigua de una API hasta la nueva, escrito para alguien con código que cambiar, no para alguien que decide si adoptar la API. Esa distinción importa: una guía de migración asume una integración existente y tráfico de producción existente, así que tiene que cubrir el rollback, la migración parcial, y cómo saber si la migración funcionó, nada de lo cual necesita una guía de primera integración.

Una guía de migración suele estar entre los dos últimos: un aviso de depreciación pone en marcha un reloj, y la guía de migración es lo que quien llama sigue antes de que ese reloj se agote.

¿Cuándo necesita un cambio una guía de migración, y no solo una entrada de changelog?

Cuando hay más de un paso entre el comportamiento antiguo y el nuevo, o cuando el cambio toca suficientes puntos de llamada como para que quien llama se beneficie de un ejemplo trabajado más que de una descripción. Qué es un cambio incompatible, y cómo lanzarlo cubre la prueba de si un cambio es incompatible; si la respuesta es sí, la segunda pregunta es si el arreglo es una edición de una línea o una migración de verdad. Un campo renombrado puede manejarlo quien llama solo con la entrada de changelog. Un cambio en autenticación, paginación o manejo de errores casi siempre se gana una guía, porque el código de reemplazo correcto no es obvio a partir de una descripción de una frase.

¿Qué necesita contener una guía de migración?

Cinco cosas, y saltarse cualquiera de ellas es cómo una guía se convierte en una página que quien llama lee una vez y luego abandona por ensayo y error. El código antiguo, mostrado tal como aparecería realmente en un proyecto. El código nuevo, mostrado igual, no como una descripción abstracta de la diferencia. Qué se rompe si no se cambia nada, dicho claramente, porque “nada” es una respuesta válida y común que quien llama igual necesita oír explícitamente. Una forma de verificar que la migración funcionó, como un campo de respuesta o un código de estado a comprobar. Y un calendario: cuándo deja de funcionar el comportamiento antiguo, y si ambas formas están disponibles mientras tanto.

## Migrando campos de moneda de float a entero (v3.0.0)

Antes:
  { "amount": 19.99 }

Después:
  { "amount": 1999 }  // unidad monetaria más pequeña (centavos)

Qué cambia: `amount` ahora es un entero en la unidad más pequeña de
la moneda de la cuenta. El código que lee `amount` como float leerá
un valor 100 veces demasiado grande a partir del 1 de octubre de 2026.

Verificar: tras migrar, un cargo de 19,99 debería leerse como
`amount: 1999`, no como `amount: 19.99`.

Calendario: v2 sigue devolviendo floats hasta el 15 de enero de 2027.
v3 devuelve enteros desde el lanzamiento. Ambas versiones están
activas ahora.

Cada una de esas cinco cosas responde a una pregunta que quien llama tendría que adivinar o preguntar al soporte, y ese es el coste real que ahorra una guía de migración.

¿Quién debería escribirla, y cuándo?

Quien diseñó el cambio, en el mismo momento en que se lanza, no un equipo de soporte reconstruyéndola a partir de tickets después. Quien tomó la decisión sabe qué partes del comportamiento antiguo nadie debería haber asumido y cuáles eran un contrato accidental; una guía escrita después por alguien sin ese contexto tiende a sobreexplicar lo obvio o a pasar por alto el único caso límite que realmente rompe a la gente. La guía y la entrada de changelog que anuncia el cambio incompatible deberían salir juntas, con la entrada enlazando a la guía en vez de repetirla.

¿Cómo se relaciona esto con el versionado y el changelog de API?

Directamente: una guía de migración es la versión detallada de lo que una entrada MAJOR en semantic versioning y tu changelog solo resume en una frase. La entrada de changelog dice que un cambio es incompatible y a grandes rasgos qué cambió; la guía de migración es el enlace que esa entrada debería llevar. Changelog de API: qué publicar y quién lo lee lista la guía de migración como uno de cinco documentos que mantiene una API, cada uno respondiendo una pregunta distinta; esta es la que responde “cómo paso realmente de A a B”, y se gana su propia página precisamente porque esa respuesta suele ser demasiado larga para una entrada de changelog.

¿Cuánto tiempo debería seguir publicada una guía de migración?

Al menos mientras el comportamiento antiguo siga siendo alcanzable, e idealmente después también. Quien migra dieciocho meses tarde, tras ignorar tres avisos de depreciación, sigue necesitando la guía, y borrarla el día en que se apaga el comportamiento antiguo solo garantiza que quien más la necesita no la encuentre. Mantenla en una URL estable y actualiza la sección de calendario en vez de retirar la página. La propia guía de actualización de Stripe es un ejemplo público de este patrón: una sola página, mantenida al día lanzamiento tras lanzamiento, en lugar de un documento nuevo por versión que queda obsoleto en cuanto sale el siguiente. Tu propia guía merece un sitio igual de fácil de encontrar, junto a la documentación que quien llama ya está leyendo, en vez de enterrada en un archivo de blog.

FAQ

¿Necesita cada cambio incompatible una guía de migración? No. Un cambio que quien llama puede resolver solo con la entrada de changelog, como un campo renombrado con un reemplazo obvio, no necesita una guía aparte. Un cambio que toca varios puntos de llamada o necesita un ejemplo trabajado, sí.

¿Debería una guía de migración vivir con la documentación de la API o en el changelog? Con la documentación, enlazada desde la entrada de changelog. La entrada es lo primero que ve una suscriptora; la guía es lo que necesita en cuanto decide actuar, y pertenece junto al material de referencia que quien llama ya está usando.

¿Cuál es la diferencia entre una guía de migración y un aviso de depreciación? Un aviso de depreciación indica que algo va a desaparecer y para cuándo. Una guía de migración son las instrucciones de qué hacer al respecto. Un aviso de depreciación sin guía de migración enlazada le da a quien llama un plazo sin decirle cómo cumplirlo.

¿Deberían documentarse tanto el comportamiento antiguo como el nuevo durante una ventana de migración? Sí, en la misma página si es posible, para que quien llama vea exactamente qué cambió en vez de reconstruirlo a partir de dos documentos separados escritos en momentos distintos.

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