Versionado de APIs (v1, v2 en endpoints)

1 Introducción

Con el tiempo, toda API necesita evolucionar:

  • Se agregan nuevas funcionalidades.
  • Se cambian estructuras de datos.
  • Se eliminan campos obsoletos.

👉 El problema: ¿cómo mejorar la API sin romper a los clientes que ya la usan? La solución es el versionado de APIs, que permite mantener varias versiones en paralelo.

2 ¿Qué es el versionado de APIs?

El versionado es la práctica de asignar un número de versión a la API (ejemplo: v1, v2) para indicar qué conjunto de reglas, endpoints y respuestas se aplica.

Beneficios

  • Compatibilidad hacia atrás: los clientes actuales pueden seguir usando la versión vieja.
  • Facilita la evolución de la API sin interrumpir servicios.
  • Ofrece un camino controlado para que los clientes migren a la nueva versión.

3 Estrategias comunes de versionado

Existen varias formas de implementar versiones en APIs REST:

1) Versión en la URL (la más usada)

/api/v1/usuarios
/api/v2/usuarios

Ventajas: claro y fácil de entender; compatible con navegadores, Postman y cURL.

Desventajas: la URL cambia con cada versión, lo que puede generar duplicación de código.

2) Versión en el header

GET /usuarios
Accept: application/json; version=2

Ventajas: la URL permanece igual; el cliente decide la versión mediante un header.

Desventajas: menos visible a simple vista; más difícil de probar directamente en el navegador.

3) Versión en el parámetro de query

GET /usuarios?version=2

Ventajas: fácil de implementar.

Desventajas: no es estándar; puede generar confusión si se mezclan con otros query params.

4 Ejemplo práctico de versionado

Versión 1 (v1)

GET /api/v1/usuarios/1

Respuesta:
{
  "id": 1,
  "nombre": "Ana"
}

Versión 2 (v2)

GET /api/v2/usuarios/1

Respuesta:
{
  "id": 1,
  "nombre": "Ana",
  "email": "ana@ejemplo.com",
  "telefono": "+54 351 1234567"
}

👉 La v2 agrega nuevos campos (email, telefono) sin romper la v1.

5 Migración entre versiones

Cuando se lanza una nueva versión:

  • Mantener la versión anterior activa por un tiempo.
  • Notificar a los clientes de los cambios (changelog).
  • Dar un periodo de transición para migrar.
  • Deprecar la versión vieja solo cuando la mayoría ya migró.

Ejemplo de mensaje de deprecación

{
  "aviso": "La versión v1 quedará obsoleta en diciembre 2025. Por favor migre a v2."
}

6 Buenas prácticas en versionado

  • Incluir siempre la versión desde el inicio de la API (v1) para evitar problemas futuros.
  • Usar URLs claras cuando se opte por versionado en la ruta.
  • Documentar bien los cambios entre versiones (Swagger / OpenAPI o changelog).
  • Evitar romper compatibilidad: no cambiar el significado de campos existentes.
  • Agregar nuevos campos sin eliminar los viejos inmediatamente.
  • Definir políticas de deprecación claras: cuánto tiempo se mantiene una versión vieja.

7 Ejemplo en frameworks

FastAPI (Python)

from fastapi import FastAPI

app = FastAPI()

@app.get("/api/v1/usuarios/{id}")
def get_usuario_v1(id: int):
    return {"id": id, "nombre": "Ana"}

@app.get("/api/v2/usuarios/{id}")
def get_usuario_v2(id: int):
    return {"id": id, "nombre": "Ana", "email": "ana@ejemplo.com"}

Express (Node.js)

const express = require("express");
const app = express();

app.get("/api/v1/usuarios/:id", (req, res) => {
  res.json({ id: req.params.id, nombre: "Ana" });
});

app.get("/api/v2/usuarios/:id", (req, res) => {
  res.json({ id: req.params.id, nombre: "Ana", email: "ana@ejemplo.com" });
});

app.listen(3000, () => console.log("Servidor en http://localhost:3000"));

👉 Cada versión se mantiene independiente, permitiendo cambios sin romper la anterior.

8 Conclusión del capítulo

El versionado de APIs es necesario para permitir la evolución sin romper integraciones existentes.

  • La forma más común es poner la versión en la URL (/api/v1, /api/v2).
  • También existen enfoques con headers o query params.
  • Buenas prácticas: mantener compatibilidad, documentar cambios, dar tiempo de transición, definir políticas de deprecación.

👉 En resumen: el versionado es la clave para APIs REST duraderas y confiables.

Retornar