StackPractices
intermediate Por Mathias Paulenko

Guía Completa de Estrategias de Versionado de APIs

Compara versionado por URI, header, query-param y negociación de contenido para REST, más evolución de esquema GraphQL y migración.

Introducción

El versionado de APIs es el mecanismo que permite a una API evolucionar sin romper los clientes que ya dependen de ella. Toda API publicada es un contrato: apps móviles ancladas a una build vieja, integraciones de socios que nadie quiere tocar, scripts corriendo en cron jobs que alguien olvidó que existían. Cambia el contrato debajo de ellos — renombra un campo, endurece un tipo, reestructura una respuesta — y esos clientes fallan en silencio o en voz alta, normalmente en producción.

La parte incómoda: reequipar versionado a posteriori duele, así que la decisión de versionar llega antes de tener un problema de versionado. Esta guía compara las cuatro estrategias REST (ruta URI, parámetro de query, header, negociación de contenido), cubre el modelo distinto de GraphQL y recorre el ciclo completo — deprecación, sunset y migración — porque publicar v2 es la mitad fácil; retirar v1 sin romper a nadie es la difícil.

¿Por Qué Versionar APIs?

  • Compatibilidad hacia atrás: los clientes existentes siguen funcionando cuando añades o cambias campos — no necesitan un deploy coordinado con el tuyo.
  • Breaking changes controlados: introduces v2 mientras v1 sigue corriendo, así la migración es una decisión que toma el cliente, no un incidente que descubre.
  • Timeline de deprecación claro: los consumidores saben cuándo migrar y tú sabes cuándo puedes retirar.
  • Experimentación segura: prueba comportamientos nuevos en una versión nueva o en un subconjunto del tráfico sin afectar a v1.

Un matiz que conviene decir pronto: versionas por cambios que rompen, no por cada release. Si un cambio es aditivo — un campo nuevo, un endpoint nuevo — sale en la versión actual. Reserva los números de versión para cambios que romperían clientes existentes; si no, acabas en /v17 sin motivo.

Elegir una Estrategia

Antes del código, la decisión:

Flujo de decisión para elegir una estrategia de versionado REST: una API pública con muchos consumidores apunta a versionado por ruta URI; servicios internos o control fino apuntan a versionado por header; necesitar URIs limpias con default-a-última apunta a query param; REST estricto con media types apunta a negociación de contenido.

No hay una respuesta universalmente correcta — pero sí una dominante. El versionado por ruta URI ganó el mercado en APIs públicas porque hace la versión imposible de perder: está en la URL, en los logs, en la clave de caché del CDN, en cada respuesta de Stack Overflow. Las alternativas cambian esa visibilidad por pureza HTTP, que le importa más al purista de la spec que al desarrollador integrando tu API a las 2 de la madrugada. La pregunta no es “cuál es más RESTful” — es “¿qué modo de fallo manejan mejor tus consumidores?” Una versión por header invisible falla cuando alguien olvida mandarla; una /v2/ visible solo falla si la quitas.

Estrategias de Versionado REST

1. Versionado por Ruta URI

El enfoque más común: la versión forma parte de la URL. /api/v1/users y /api/v2/users son literalmente recursos distintos, así que routing, caché, logs y documentación funcionan sin tratamiento especial.

from fastapi import FastAPI, APIRouter

app = FastAPI()

v1_router = APIRouter(prefix="/api/v1")
v2_router = APIRouter(prefix="/api/v2")

@v1_router.get("/users/{user_id}")
async def get_user_v1(user_id: str):
    return {"id": user_id, "name": "Alice", "email": "alice@example.com"}

@v2_router.get("/users/{user_id}")
async def get_user_v2(user_id: str):
    return {"id": user_id, "name": "Alice", "email": "alice@example.com", "created_at": "2024-01-01"}

app.include_router(v1_router)
app.include_router(v2_router)

Ventajas: simple, explícito, cacheable, visible en logs, fácil de enrutar y deprecar. Contras: “contaminación” de URIs, rompe la pureza REST (una versión no es un recurso) y anima a mantener árboles de rutas paralelos.

En la práctica los contras importan menos de lo que suenan — toda API pública grande (Stripe, Twilio, GitHub) usa alguna variante de versionado por ruta, porque los consumidores leen URLs más que headers. Monta las versiones a nivel de router (como arriba) en vez de duplicar endpoints, así el árbol de v1 queda congelado mientras v2 evoluciona.

2. Versionado por Parámetro de Query

La versión viaja como parámetro de query: /users/123?version=2. Las URIs quedan limpias y es trivial por defecto a la última cuando el parámetro falta.

from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: str, request: Request):
    version = request.query_params.get("version", "1")

    if version == "1":
        return {"id": user_id, "name": "Alice"}
    elif version == "2":
        return {"id": user_id, "name": "Alice", "email": "alice@example.com"}
    raise HTTPException(status_code=400, detail="Unsupported version")

Ventajas: URIs limpias, default-a-última fácil, sin headers extra. Contras: invisible en logs salvo que registres query strings, fácil de olvidar para los clientes, y la caché es frágil — una clave de caché compartida debe incluir el parámetro o las respuestas de v1 y v2 se mezclan.

La cautela de caché es la trampa real: si un CDN o proxy no trata ?version= como parte de la clave de caché, un cliente puede envenenar la caché con el payload de la otra versión. El default a “última” también suena amable hasta que un cliente que quería v1 recibe silenciosamente v2 tras un deploy — fija el default a una versión y migra deliberadamente, o exige el parámetro explícito.

3. Versionado por Header

La versión sale de la URI por completo a un header personalizado — típicamente X-API-Version: 2. La URI describe el recurso; el header describe el contrato.

from fastapi import FastAPI, Header, HTTPException

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(
    user_id: str,
    x_api_version: str = Header(default="1", alias="X-API-Version"),
):
    if x_api_version == "1":
        return {"id": user_id, "name": "Alice"}
    elif x_api_version == "2":
        return {"id": user_id, "name": "Alice", "email": "alice@example.com"}
    raise HTTPException(status_code=400, detail="Unsupported version")

Ventajas: URIs limpias, RESTful (la versión es metadato, no recurso), granularidad fina. Contras: invisible en logs y en las dev tools del navegador, más difícil de probar a mano, y no cacheable por defecto — la caché debe variar por el header.

Esta es la estrategia que prefieren los service meshes internos: cuando ambos extremos son tu propio código, un header va bien porque ningún humano necesita verlo. Para APIs públicas es una venta difícil — un consumidor que prueba tu API con curl o un navegador no ve la versión en absoluto, y olvidar el header significa caer silenciosamente en la versión que hayas elegido por defecto.

4. Negociación de Contenido (Accept Header)

La opción “purista”: la versión forma parte del propio media type, así que /users/123 devuelve application/vnd.example.v1+json o application/vnd.example.v2+json según el header Accept que mande el cliente.

from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: str, request: Request):
    accept = request.headers.get("accept", "")

    if "application/vnd.example.v1+json" in accept:
        return {"id": user_id, "name": "Alice"}
    elif "application/vnd.example.v2+json" in accept:
        return {"id": user_id, "name": "Alice", "email": "alice@example.com"}

    raise HTTPException(status_code=406, detail="Unsupported media type")

Ventajas: estrictamente RESTful (el media type lleva el contrato), sigue la spec HTTP, las URIs más limpias posibles. Contras: lo más duro para el consumidor — Accept: application/vnd.example.v2+json es un trabalenguas, los navegadores no lo prueban, y Accept ya está sobrecargado para negociación de formato (JSON vs XML).

La negociación de contenido es la más correcta y la menos querida. Brilla en APIs hipermedia y programas de API formales (es lo que usaba la API de GitHub antes de pasar a X-GitHub-Api-Version), pero para la mayoría de equipos el coste de DX no compensa la ganancia de pureza — un Accept que nadie recuerda mandar bien falla más que una ruta /v2/.

Comparación

EstrategiaVisibilidadCachéRESTfulComplejidadIdeal para
Ruta URIAltaFácilNoBajaAPIs públicas, lo más común
Query ParamMediaMás difícilSíBajaAPIs internas, default-a-última
HeaderBajaDifícilSíMediaAPIs internas, control fino
Negociación de contenidoBajaDifícilSíAltaREST estricto, media types

Lee la columna “Caché” con atención — es la que muerde en producción. Las versiones por ruta son gratis en cualquier CDN y navegador; cualquier cosa en header o query param exige que la caché varíe por esa clave, y una caché que no lo hace devuelve la versión equivocada al cliente equivocado — un modo de fallo sutil y brutal que solo aparece con tráfico real.

Evolución de Esquema GraphQL

GraphQL rechazó el versionado por diseño — en vez de congelar endpoints, el esquema evoluciona. La regla de oro: siempre puedes añadir, nunca puedes quitar sin romper a alguien.

Cambios aditivos (sin versión)

type User {
  id: ID!
  name: String!
  email: String!      # New field — old clients ignore it
  createdAt: String   # New field — nullable for backward compat
}

Deprecar campos

type User {
  id: ID!
  name: String!
  email: String!
  username: String @deprecated(reason: "Use email instead")
}

Breaking changes (nuevo esquema o directiva)

const { buildSchema } = require("graphql");

// Option 1: Run two schemas on different endpoints
const v1Schema = buildSchema(`
  type User { id: ID!, name: String! }
`);
const v2Schema = buildSchema(`
  type User { id: ID!, name: String!, email: String! }
`);

// Option 2: Use @specifiedBy or custom directives for feature flags
const schema = buildSchema(`
  type User {
    id: ID!
    name: String!
    email: String
  }
`);

Buenas prácticas de versionado GraphQL

  • Añade campos, nunca quites — los clientes viejos siguen funcionando porque solo piden lo que conocen.
  • Depreca antes de eliminar — la directiva @deprecated marca el campo en el esquema y en la introspección de GraphiQL.
  • Haz los campos nuevos nullable — los datos viejos pueden no tener el valor; un campo nuevo no-null rompe queries contra registros existentes.
  • Usa schema stitching/federation para versiones mayores — enruta queries a un subgrafo v1 o v2 en vez de un monolito.
  • Mide el uso de campos — solo elimina campos deprecados cuando la analítica de queries muestre uso cero; GraphQL lo hace medible porque los clientes declaran exactamente qué campos quieren.

Para más profundidad, la guía de diseño de esquemas GraphQL.

Deprecación y Sunset

Una versión sin plan de salida es una versión para siempre. Los headers estándar de industria son Deprecation y Sunset — definidos en el Internet-Draft que se convirtió en la línea RFC del deprecation-header (RFC 8594 es el borrador antiguo de Sunset; el par moderno es Deprecation: true + Sunset: <HTTP-date>), y son legibles por máquina, así que gateways y clientes HTTP pueden avisar automáticamente.

Headers de deprecación

from fastapi import FastAPI, Response

app = FastAPI()

@app.get("/api/v1/users/{user_id}")
async def get_user_v1(user_id: str, response: Response):
    response.headers["Deprecation"] = "true"
    response.headers["Sunset"] = "Sun, 01 Jun 2025 00:00:00 GMT"
    response.headers["Link"] = '</api/v2/users/{user_id}>; rel="successor-version"'
    return {"id": user_id, "name": "Alice"}

El header Link apuntando al sucesor es la parte que todos se saltan — y es la más útil: un cliente que lo parsea sabe exactamente a dónde ir, sin documentación.

Timeline de deprecación

  1. Anuncia: añade Deprecation: true, actualiza docs, publica una guía de migración.
  2. Notifica: email a consumidores de la API; loguea avisos de deprecación en cada llamada.
  3. Sunset: añade el header Sunset con fecha de retirada — mínimo 6 meses, 12+ para APIs públicas.
  4. Monitoriza: mide el uso del endpoint deprecado — eso decide tu fecha real.
  5. Retira: tras el sunset, devuelve 410 Gone — no 404 — para que los clientes distingan “retirado” de “URL equivocada”.

Dos detalles que el timeline esconde: monitoriza primero, borra después — si la gráfica de uso sigue mostrando tráfico a un mes del sunset, extiendes la fecha o aceptas romper a esos clientes a sabiendas; y una respuesta 410 Gone es tu última pieza de documentación, así que haz que el body apunte a la guía de migración una última vez.

Patrones de Migración

Publicar v2 es fácil; mover el tráfico fuera de v1 sin una caída es el proyecto. Dos patrones dominan.

Patrón Strangler Fig

Enruta por ruta: los endpoints nuevos van a v2, los viejos quedan en v1, y los migrados hacen proxy — así la URL de fachada nunca cambia mientras la implementación de debajo se sustituye.

from fastapi import FastAPI, Request
import httpx

app = FastAPI()

@app.api_route("/api/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def router(path: str, request: Request):
    # New endpoints handled by v2
    if path.startswith("v2/"):
        return await handle_v2(request)

    # Old endpoints — check if migrated
    migrated = ["users", "orders"]  # endpoints that moved to v2
    base_path = path.split("/", 1)[0] if "/" in path else path

    if base_path in migrated:
        # Proxy to v2 with response transformation
        return await proxy_to_v2(request)

    # Not migrated — serve from v1
    return await handle_v1(request)

Parallel run (shadow deployment)

Corre ambas versiones contra tráfico real pero sirve solo v1: v2 ejecuta en segundo plano, las respuestas se comparan y los desajustes se loguean — así descubres las diferencias de v2 con datos de producción y cero riesgo.

import asyncio
import logging

logger = logging.getLogger("api_migration")

async def parallel_run(v1_handler, v2_handler, request):
    # Serve from v1 (source of truth)
    v1_response = await v1_handler(request)

    # Run v2 in background, compare results
    try:
        v2_response = await v2_handler(request)
        if v1_response != v2_response:
            logger.warning(f"Response mismatch: v1={v1_response}, v2={v2_response}")
    except Exception as e:
        logger.error(f"v2 handler failed: {e}")

    return v1_response

La cautela de producción: los shadow runs duplican la carga de los endpoints ensombrecidos — elige un porcentaje de tráfico, no todo. El logging de desajustes debería capturar también la petición, o tendrás diffs que no puedes reproducir. Cuando los mismatches se mantengan en cero una semana, cambia la fuente de verdad y el patrón se convierte en un cutover strangler.

Cuándo NO Versionar

La parte contraria del versionado: a veces la respuesta correcta es no versionar en absoluto. Tres casos donde una versión nueva es la herramienta equivocada:

  • APIs internas con un solo consumidor. Si tu propio frontend es el único cliente y despliegas ambos juntos, el versionado compra ceremonia — despliégalos como unidad y deja que el pipeline de release sea el contrato. El versionado compensa cuando los clientes despliegan en tu horario, no en el suyo.
  • Evolución solo aditiva. Si cada cambio que planeas es un campo o endpoint nuevo, el número de versión es peso muerto — el modelo de GraphQL aplica también a REST: evoluciona aditivamente, marca lo viejo como deprecado y la versión se queda en 1 para siempre.
  • El cambio es un bug fix. Una respuesta rota alrededor de la cual los consumidores construyeron workarounds sigue siendo un bug fix, no un breaking change — versionas el contrato, no la implementación. Si v1 documentaba total: int y devolvía un string, arreglarlo no es v2 — es un parche con una entrada ruidosa en el changelog.

La meta-regla: una versión es una promesa de mantener dos contratos para siempre. Asume esa carga de mantenimiento solo cuando la alternativa — romperle la producción a alguien — es peor.

Playbook de Rollout de Versionado

Publicar una versión nueva es un programa, no un deploy. La secuencia que funciona:

  1. Congela la semántica de v1. Antes de que exista v2, decide qué significa v1 — su comportamiento ahora es una spec contra la que testeas, no código que refactorizas. Cualquier cambio en v1 más allá de parches de seguridad reabre la pregunta “¿qué v1?”.
  2. Publica v2 con el mismo auth. No hagas que los consumidores se re-incorporen — la misma API key, los mismos scopes, otra ruta. Cada reset de credenciales es un punto de abandono de la migración.
  3. Publica el diff, no la doc. “Qué cambió en v2” — una tabla campo a campo — convierte mejor que una referencia nueva. Los consumidores no quieren reaprender la API; quieren saber qué les rompe.
  4. Corre el shadow. Usa el patrón parallel-run sobre una porción de tráfico hasta que los desajustes lleguen a cero.
  5. Depreca in-band y out-of-band. Los headers llegan a las máquinas; los emails y dashboards llegan a los humanos que deciden migrar. Necesitas ambos.
  6. Sunset por dato, no por fecha. El día de retirada llega cuando la gráfica de uso dice que el tráfico restante está migrado o abandonado conscientemente — lo que ocurra primero.

El paso que todos se saltan es el 3: la mayoría de quejas de “v2 adopta lento” vienen de una doc de migración que reenseña la API en vez de listar los deltas.

Testing Entre Versiones

La coexistencia es donde el versionado vive o muere — y donde las suites de tests van a pudrirse. Las reglas:

  • Contract-testa cada versión activa. Los tests de v1 siguen corriendo tras publicar v2 — esa es la razón de ser de la versión. Si los tests de v1 se borran porque “nadie lo usa”, ya no sabes qué hace v1.
  • Testea la frontera, no solo las versiones. Los bugs interesantes viven donde las versiones se encuentran: un cliente v1 pegándole a un campo v2, un middleware que asume una forma de respuesta, una clave de caché compartida entre versiones.
  • Fija las versiones en los tests explícitamente. Un test que depende de “la versión por defecto” falla el día que el default se mueve — escribe ?version=1 o el header en la petición, siempre.
  • Haz snapshot de la superficie deprecada. Al deprecar, captura las respuestas actuales de v1 como fixtures — son el contrato que prometes mantener hasta el sunset. Si una refactorización las cambia, el test lo caza antes que un cliente.

Buenas Prácticas

  • Empieza con versionado por ruta URI en APIs públicas — lo más intuitivo para consumidores; guarda estrategias exóticas para servicios internos.
  • Versiona a nivel de router, no por endpoint — versiones consistentes en toda la superficie de la API.
  • Mantén las versiones viejas corriendo — al menos 6 meses tras el anuncio de deprecación, más para APIs públicas.
  • Usa versionado semántico en SDKs — major.minor.patch; los cambios que rompen suben el major.
  • Documenta los cambios entre versiones — los changelogs son obligatorios en APIs públicas (la plantilla api-changelog cubre el formato).
  • Monitoriza el uso por versión — no retires una versión que aún tenga tráfico; deja que el dato marque la fecha.
  • Prefiere cambios aditivos — un campo o endpoint nuevo sale en la versión actual; reserva las versiones nuevas para lo que rompe.
  • Usa feature flags para rollout gradual — prueba comportamientos nuevos con un porcentaje de tráfico antes de comprometerte.
  • Publica guías de migración — una doc v1→v2 paso a paso convierte más usuarios que cualquier header de deprecación.
  • Pon rate limits más bajos a las versiones viejas — un incentivo suave y honesto para migrar.

Errores Comunes

  • No versionar desde el día uno — reequipar versionado en una API con clientes vivos duele y siempre cuesta más que hacerlo desde el principio.
  • Breaking changes sin versión nueva — los clientes se rompen en silencio; el número de versión existe precisamente para evitarlo.
  • Retirar versiones viejas demasiado rápido — los clientes necesitan tiempo de migración medido en meses, no semanas.
  • Sin headers de deprecación — los clientes descubren la retirada cuando su integración se rompe, no antes.
  • Versionar cada cambio menor — los cambios aditivos no necesitan versión nueva; así es como las APIs acaban en /v17.
  • Sin docs de diferencias entre versiones — los consumidores adivinan qué cambió; un changelog lo responde.
  • Mezclar estrategias de versionado — /v2/ aquí, ?version= allá — elige una y aplícala en todas partes.
  • No testear las versiones viejas tras desplegar las nuevas — las regresiones en v1 pasan desapercibidas hasta que un cliente las reporta.

Troubleshooting

  • Clientes recibiendo silenciosamente la versión equivocada: normalmente un header ausente o un default sin fijar — comprueba si la petición llevaba X-API-Version/?version= y fija los defaults a una versión concreta en vez de “latest”.
  • Caché sirviendo versiones mezcladas: la clave de caché no incluye la versión — añade el header/parámetro a Vary o a la clave del CDN; con versionado por ruta esto no puede pasar.
  • 404 tras el sunset: confirma que la versión vieja está realmente retirada y no solo movida — sirve 410 Gone con puntero a la guía de migración, no un 404 desnudo.
  • Los consumidores nunca vieron la deprecación: comprueba que los headers Deprecation/Sunset les llegan — algunos proxies quitan headers desconocidos; acompaña los headers con anuncios por email/docs.
  • Tests condicionados por versión fallando: fija la versión del test client explícitamente — un default que se mueve con los deploys rompe tests de forma no determinista.

See Also

Lecturas Recomendadas

Preguntas frecuentes

¿Cuándo debería crear una nueva versión de API?

Crea una versión nueva cuando hagas breaking changes: eliminar campos, cambiar tipos de campo, cambiar la estructura de respuesta, cambiar códigos de error o alterar la autenticación. Los cambios aditivos — campos nuevos, endpoints nuevos — no requieren versión nueva; salen en la actual.

¿Debería versionar APIs GraphQL?

No — GraphQL está diseñado para evolución de esquema. Añade campos, depreca los viejos con @deprecated y haz los campos nuevos nullable. Solo crea un esquema nuevo para cambios verdaderamente incompatibles, e incluso entonces considera correr dos esquemas en paralelo detrás del mismo endpoint.

¿Cuánto tiempo debería soportar versiones viejas de API?

Mínimo 6 meses para APIs internas, 12–24 meses para públicas — y deja que decida el uso, no el calendario. Monitoriza el tráfico en endpoints deprecados y no retires una versión que siga moviendo carga real; una fecha de sunset es una promesa que extiendes, no un temporizador que obedeces ciegamente.