¿Cuáles son las principales estrategias de versioning de API, y cómo se deprecia una versión?

Question

IT Interview Practice · Accepted Answer

El versioning te permite evolucionar una API con **breaking changes** sin romper los clients existentes. Hay tres estrategias predominantes, más un proceso de deprecación.

## Las tres estrategias

**1. URI versioning** — la versión va en el path.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
La más simple y visible; fácil de rutear, cachear y probar en un navegador. Desventaja: técnicamente viola "el URI identifica un recurso" (el mismo user tiene ahora dos URLs). Es de lejos la opción más común (GitHub, Stripe históricamente).

**2. Custom header versioning** — la versión viaja en una cabecera.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Mantiene las URLs limpias pero es invisible en un navegador y más difícil de cachear.

**3. Media-type (content negotiation) versioning** — la versión en `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
La más "RESTful" (la URL del recurso es estable; solo se versiona su representación), pero la menos accesible para los consumidores.

## Qué cuenta como breaking

```text
BREAKING      → quitar/renombrar un field, cambiar un tipo, cambiar auth, endurecer la validación
NON-BREAKING  → añadir un field opcional nuevo, añadir un endpoint nuevo, añadir un valor de enum*
```
Solo los breaking changes necesitan una versión nueva; añade los cambios non-breaking a la versión actual.

## Proceso de deprecación

1. **Anuncia** con fechas en la documentación y el changelog.
2. **Señaliza en runtime** con cabeceras para que los clients se enteren de forma programática:
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. **Monitoriza** el uso de la versión antigua y contacta con los llamantes restantes.
4. **Retira (sunset)** solo cuando el uso caiga cerca de cero.

## Por qué es importante

Los entrevistadores preguntan esto para ver si puedes hacer crecer una API en producción sin romper los clients que dependen de ella — una preocupación operativa real, no teórica. Las respuestas más fuertes hacen dos distinciones: primero, que **la mayoría de los cambios son non-breaking** y no deberían provocar un bump de versión en absoluto (los cambios aditivos van a la versión actual), reservando el versioning para los breaking changes genuinos; y segundo, que la *estrategia* importa menos que el *proceso* — un calendario de deprecación claro con cabeceras `Deprecation`/`Sunset` y monitorización del uso es lo que de verdad protege a los consumidores. El URI versioning gana en la práctica por su visibilidad y soporte de tooling, pero conocer los compromisos (header y media-type mantienen las URLs estables y son más RESTful, a costa de la descubribilidad) demuestra que entiendes el espacio de diseño en lugar de solo imitar `/v1/`.

Las tres estrategias

Qué cuenta como breaking

Proceso de deprecación

Por qué es importante

Preguntas relacionadas