Hola devs, esta vez toca un artículo de algo muy usado en la industria que es el API Versioning y haré dos artículos, en este te hablaré toda la teoría que deberías conocer y en el siguiente cómo implementarlo, así que... comencemos!
Imagina esto: tienes una API en producción funcionando perfectamente. Cientos de clientes la consumen diariamente. Ahora necesitas hacer cambios que rompan la compatibilidad hacia atrás. ¿Qué haces?
Respuesta corta: Versionas tu API.
Como ya sabrás, estimado dev, el versionamiento de APIs es una de las decisiones más importantes al diseñar una API REST. Sin él, cualquier cambio que hagas puede romper la aplicación de tus clientes. Con él, puedes evolucionar tu API sin causar caos.
En este artículo te explico los conceptos fundamentales y te muestro cómo implementé versionamiento de APIs en un proyecto real ASP.NET Core con Clean Architecture.
¿Qué es el versionamiento y cuándo deberías hacerlo?
El versionamiento de APIs es el proceso de gestionar cambios en tu API de manera que las aplicaciones cliente puedan seguir funcionando mientras tú introduces nuevas funcionalidades o modificas las existentes.
Versiona cuando:
- Vas a cambiar el formato de respuesta de un endpoint
- Vas a modificar la estructura de un request
- Vas a eliminar campos o endpoints
- Vas a cambiar la lógica de negocio de manera significativa
No necesitas versionar cuando:
- Solo agregas nuevos endpoints opcionales
- Agregas campos nuevos que el cliente puede ignorar
- Corriges bugs sin cambiar contratos
Y por si no sepas si debes versionar o no, te cuento crack que la regla de oro es: Si el cliente necesita cambiar su código para adaptarse a tu API, necesitas una nueva versión.
Estrategias de versionamiento
Existen tres estrategias principales para versionar APIs REST:
1. URL Path Versioning (más común)
La versión se incluye en la URL del endpoint:
GET /api/v1/products
GET /api/v2/products
Las ventajas son muchas por ejemplo:
- Visibilidad inmediata (sabes qué versión estás llamando)
- Fácil de probar en el navegador
- Simple de implementar
- Cache-friendly
Como todo en la vida, no es perfecto, entre sus "desventajas" tenemos:
- Rompe la idea de que una URL identifica un recurso único
- Puede parecer "verboso" para algunos
2. Header Versioning
Aquí la versión se envía en un header HTTP:
GET /api/products HTTP/1.1
X-Api-Version: 2.0
Ventajas:
- URLs más limpias
- El recurso y su versión están separados conceptualmente
Desventajas:
- Más difícil de probar en el navegador
- Requiere configuración adicional en clientes
- Problemas con cachés intermedios
3. Query String Versioning
La versión se pasa como parámetro de query, algo así...
GET /api/products?version=2.0
Ventajas:
- URLs flexibles
Desventajas:
- Menos intuitivo
- Puede olvidarse fácilmente
- Mezcla parámetros de versión con parámetros de consulta
Mi recomendación: Usa URL Path Versioning
Después de probar las tres estrategias, me quedo con URL Path Versioning por estas razones:
- Es explícito — tanto tú como el cliente saben exactamente qué versión están usando
- Es debuggable — puedes copiar la URL y probarla directamente
- Es simple — no requiere configuración especial
- Funciona perfectamente con Swagger — la documentación se organiza de forma natural
Además, es la que la industria más utiliza.
Si quieres aprender a implementarla, te espero en el siguiente artículo!
Si esta entrada te ha gustado, compártela!
Créditos de imagen de portada: Foto de 🇸🇮 Janko Ferlič en Unsplash