Tu API tiene consumidores que no publican según tu calendario. La integración de un socio la escribió alguien que dejó la empresa hace dos años. El script de automatización de un comerciante no se ha tocado desde que se escribió, y nadie recuerda que existe hasta que se rompe. Cambiarás tu API para siempre, y cada cambio es una negociación con código que no puedes ver y no puedes desplegar.
Este capítulo cubre la mecánica de esa negociación: distinguir un cambio rompedor de uno seguro, resolver una versión en el borde en lugar de esparcir condicionales por los controladores, servir dos versiones desde una sola base de código, poner una fecha de deprecación real en lugar de una promesa vaga, avisar a quien consume antes de que se entere por las malas, escribir una guía de migración que alguien pueda seguir, y retirar una versión cuando llegue su hora.
Una versión es una promesa con fecha de caducidad, no una bifurcación permanente. Todo lo que sigue existe para cumplir esa promesa sin congelar tu base de código en ámbar.
Cambios que rompen y cambios que no
La mayoría de las conversaciones sobre versionado empiezan demasiado tarde, en el punto en que alguien ya rompió algo y se discute cómo llamar al arreglo. Empieza antes: sabe qué cambios necesitan una subida de versión antes de escribir el código.
Los cambios aditivos no rompen. Añadir una clave nueva al array —digamos un campo status que nadie había pedido— no toca lo que ya estaba. Un consumidor que analiza key y domains no lo nota.
Renombrar un campo rompe. Renombra domains a verified_domains y todo consumidor que lea $data['domains'] obtiene null en el mejor caso y un error fatal en el peor.
Cambiar el tipo de un campo rompe. Que created_at pase de una cadena formateada a una marca de tiempo Unix supera todas las pruebas que escribiste tú y falla todas las que escribió quien te consume.
Eliminar un campo rompe, incluso un campo que estás seguro de que nadie usa. No tienes visibilidad del código de todos tus consumidores. Da por hecho que leen todo lo que envías.
Añadir un parámetro obligatorio en la petición rompe. Un campo opcional nuevo no cuesta nada. Uno obligatorio convierte cada llamada de creación existente en un 422.
La regla: si un cliente existente y sin modificar analizaría tu respuesta nueva o haría tu petición nueva de forma distinta a como lo hace hoy, es un cambio rompedor. Todo lo demás se publica un martes sin subir versión.