Express.js
Versionado y evolución de APIs
Explica cómo evolucionar contratos HTTP con cambios compatibles, deprecación, versionado por URL o headers y migraciones coordinadas con clientes.
- Última actualización
- Actualizada
- Nivel
- Aplicación
Express.js
Explica cómo evolucionar contratos HTTP con cambios compatibles, deprecación, versionado por URL o headers y migraciones coordinadas con clientes.
Versionar una API no significa crear una nueva versión por cada cambio. El objetivo es permitir evolución sin romper consumidores que no se actualizan al mismo ritmo.
Una API es un contrato distribuido. El servidor puede desplegar hoy, pero clientes móviles, integraciones y terceros pueden permanecer meses con una versión anterior.
La evolución debe distinguir cambios compatibles de cambios incompatibles.
Incluso un cambio “aditivo” puede romper clientes rígidos que rechazan campos desconocidos o enums nuevos. Por eso compatibilidad también depende de expectativas documentadas.
/api/v1/orders
/api/v2/ordersEs visible y fácil de enrutar, pero puede duplicar rutas y animar a versionar toda la API aunque solo cambie un recurso.
Accept: application/vnd.domisys.orders.v2+jsonMantiene URLs estables, pero complica debugging, caches y clientes.
API-Version: 2026-07-01Permite agrupar comportamiento en cortes temporales. Requiere disciplina y documentación de cada cambio.
Mantener compatibilidad y deprecar gradualmente suele ser la opción más simple para APIs internas.
Para renombrar customerName a customer:
customer sin eliminar el campo anterior.customerName.El mismo patrón aplica a bases de datos, eventos y APIs.
Una deprecación útil necesita:
Un comentario en documentación no es suficiente.
Puedes utilizar Deprecation, Sunset y enlaces de documentación cuando el ecosistema los soporte. No sustituyen comunicación directa con consumidores críticos.
No mantengas dos aplicaciones completas si solo cambia una representación. Comparte casos de uso y separa adaptadores HTTP cuando sea seguro.
Pero evita condicionales interminables:
if (version === 1) ... else if (version === 2) ...Cuando las reglas divergen de verdad, crea boundaries claros y plan de retiro.
La API no evoluciona sola. Cambios en eventos, webhooks, jobs y esquema de base deben coordinarse. Un productor no debe emitir un campo nuevo obligatorio antes de que consumidores lo entiendan.
Añadir un valor puede romper clientes con switch exhaustivo. Documenta que los clientes deben tolerar valores desconocidos o usa categorías extensibles.
DomiSys cambia status: "sent" por estados más precisos.
Mala migración:
hoy: sent
mañana: dispatchedMejor:
No crees v2 solo por refactor interno.
OpenAPI y documentación del contrato convierte estas decisiones en una especificación verificable.