Una API es un contrato. Romper ese contrato es costoso para clientes. Pero las APIs evolucionan. La pregunta es cómo hacerlo sin drama.
Versionado URL vs Header: qué opción elegir
Versionado en URL (/v1/users, /v2/users) es explícito pero genera duplicación. Versionado en header (Accept: application/vnd.api+json;version=2) es elegante pero requiere que clientes lo entienda.
Para APIs públicas, URL es más claro. Para internas, header funciona bien.
- URL: /v1/..., /v2/... Simple, explícito.
- Header: Accept-Version: 2. Elegante pero requiere conocimiento.
- La mayoría elige URL por claridad.
Deprecación: comunica cambios con anticipación
Antes de eliminar un endpoint, anúncialo. Comunica fecha de muerte. Retorna headers como Deprecation: true, Sunset: Thu, 31 Dec 2024 23:59:59 GMT.
Eso da a clientes tiempo de adaptar sin sorpresas desagradables.
- Documenta qué deprecas y cuándo.
- Retorna headers estándar.
- Mantén vieja versión funcionando tiempo suficiente.
Compatibilidad hacia adelante: sé tolerante con cambios
Si tu API puede ignorar fields que no entiende, es más resiliente. Si tu cliente puede ignorar fields nuevos, también. El objetivo es que cambios sean aditivos, no destructivos.
Eso significa: nunca remuevas campos existentes, solo añade nuevos. Nunca cambies significado de un field, solo su tipo si es compatible.
- Añade fields nuevos siempre opcional.
- Nunca remuevas fields existentes (depreca primero).
- Si cambias tipo, asegúrate que sea backward compatible.
Schema evolution: bases de datos también evolucionan
La misma lógica aplica a base de datos. Migrations que rompen existencia (eliminar columna sin default) pueden romper código viejo.
La práctica es: expansión primero, después contracción. Añade columna, deja que el código viejo siga usando la antigua, después cuando todo es nuevo, elimina la vieja.
La API y la base de datos pueden cambiar, pero ambas deben tolerar coexistencia de vieja y nueva estructura por un tiempo.
Comunicación clara es todo
Nada de cambios sorpresa. Changelog claro, emails a clientes, documentación actualizada. Cuando los cambios se comunican bien, la adopción es rápida y el drama, mínimo.
La mayoría de problemas de versionado vienen de mala comunicación, no de mala técnica.