Construir una API es fácil. Mantenerla estable mientras evoluciona tu sistema… no tanto. Cada vez que cambias un campo, modificas una respuesta o renombras un endpoint, rompes el contrato con quien usa tu API. Y eso puede tumbar sistemas en producción.

Piensa que una API es como un contrato. Describe: 👉Qué endpoints existen 👉Qué datos esperan y devuelven 👉Cómo se comporta el sistema Si cambias el contrato sin avisar, estás traicionando a quienes confían en él. Ahí entra el versionado.

El versionado de APIs da una forma estructurada de evolucionar tu API sin romper a los consumidores. Permite decir: Aquí está la versión antigua (v1) Aquí está la nueva (v2) Y cada cliente puede migrar a su ritmo.

Pero ojo, poner /v1/ en la URL no significa que estés versionando bien. He visto APIs que dicen “v1” en el path y años después siguen ahí, aunque hayan cambiado completamente. Eso no es versionar, eso es fingir estabilidad.

El versionado solo importa realmente cuando tu API es usada por otros equipos o por el público. Porque entonces no puedes romper compatibilidad sin consecuencias. Si trabajas en una empresa grande o expones APIs públicamente, necesitas un plan.

Cuando tu API cambia, tienes 3 caminos: 1️⃣ Nueva versión completa: /api/v2/orders. Segura para clientes, pero más mantenimiento. 2️⃣ Compatibilidad hacia atrás: solo añades campos opcionales. Fácil de mantener, pero limitada. 3️⃣ Romper compatibilidad: todos deben actualizar. A

Existen varias formas de aplicar versionado: 👉En el path: /api/v1/orders 👉En el query param: /api/orders?version=2 👉En el header: Accept: application/vnd.example+json;version=2 👉En el payload: { "version": "v1" } Cada una tiene ventajas y desventajas , veamos con más

1⃣Path Versioning ✅ Fácil de entender ❌ Ensucia URLs y rompe la identidad de los recursos /api/v1/orders y /api/v2/orders deberían ser el mismo recurso (un pedido), pero ahora parecen cosas distintas. Si usas este método, mantén versiones antiguas por un tiempo y anuncia la

2⃣Header Versioning Es el más limpio ya que mantiene URLs limpias GET /api/orders Accept: application/vnd.tuapi+json;version=2 Sus ventajas e inconveniente son: ✅ URLs estables ✅ Control granular ❌ Más difícil de depurar y cachear Esta es la estrategia que usan Stripe y

Piensa siempre en tu API como un contrato. Cada cambio es una negociación con tus consumidores. Versionar bien no es solo “añadir un número”, es respetar a quien depende de ti.

Si te ha gustado este tip y quieres seguir aprendiendo sobre arquitectura, buenas prácticas y cómo pensar como un desarrollador senior 👇 Échale un ojo a de CERO a SENIOR, todas las semanas consejos para tu carrera como DEV https://open.substack.com/pub/...

@juliancamposes Hay que evitar el versionado lo máximo posible de qué cojones hablas? Hay que hacerlo backwards compatible lo máximo que se pueda! Anda vete a tu curro de 20k y déjanos en paz

@juliancamposes Y le vas a responder a tu jefe que les pida a cada uno de sus millones de clientes que borren su caché (y sus galletas 🍪🍪).

chi

- Toc toc - Una función asíncrona - ¿Quién es?

Layoffs en Meta: despidos de 600 empleados del team de AI 😮

Visual studio (morado) y una llamada de teams donde comparte pantalla