Saltar al contenido
Explorar conocimiento
Portafolio

concepto · intermedio · 2 min de lectura

API Versioning

API Versioning es la práctica de gestionar cambios en una API sin romper a los clientes existentes, permitiendo que múltiples versiones de la misma API coexistan.

No requiere conocimientos previos.

Alcance en breve

Cubre

  • API Versioning as an architectural concept

No cubre

  • implementation details

Supone

  • The reader understands distributed systems concepts.

Resumen

Las APIs cambian. Un campo se renombra, un endpoint se depreca, un formato de respuesta se reestructura. Si esos cambios rompen a los clientes que dependen de la API, perdés confianza y adoptión. API Versioning es el conjunto de estrategias para evolucionar una API de forma segura.

Las estrategias más comunes:

  • URI versioning: /v1/users, /v2/users. Simple, visible, pero los clientes están atados a una versión en la URL.
  • Header versioning: Accept: application/vnd.api+json;version=2. La URL no cambia, pero requiere que los clientes envíen headers.
  • Query parameter: /users?version=2. Pragmático pero rompe el principio de que la URL identifica un recurso.
  • Content negotiation: la misma URL devuelve representaciones distintas según el Accept header. Potente pero complejo.

Alcance y supuestos

Este paquete cubre estrategias de versionado de APIs y criterios para elegir entre ellas. Asume familiaridad con diseño de APIs REST.

Modelo mental

Una autopista con carriles. Cuando agregás un carril nuevo, no cerrás los viejos: los autos modernos usan el carril rápido y los viejos siguen por el lento. Eventualmente, cuando nadie usa el carril viejo, lo cerrás. API versioning es mantener los carriles viejos abiertos mientras los clientes migran.

Uso práctico

  • ✅ Cambios que rompen compatibilidad hacia atrás —breaking changes—.
  • ❌ Cambios aditivos —agregar un campo nuevo— no requieren versioning si los clientes los ignoran.

Ejemplo trabajado: Stripe y el versionado por fecha

Stripe versiona su API con fechas en el header: Stripe-Version: 2023-10-16. Un cliente nuevo recibe la versión más reciente. Un cliente existente sigue en la versión que eligió hasta que decide migrar. Stripe mantiene versiones viejas durante años, permitiendo migraciones graduales. El equipo de Stripe puede cambiar la implementación interna de cualquier versión sin romper a los clientes.

Evidencia

  • Stripe y GitHub son referentes en API versioning: Stripe usa header con fecha, GitHub usa URI con fecha. Ambos mantienen versiones viejas durante años.

Fuentes citadas