Estrategias de Versionado de API - Diseno que Mantiene la Compatibilidad hacia Atras

Que es el Versionado de API

El versionado de API es un mecanismo para evolucionar la API sin romper los clientes existentes. Al introducir cambios disruptivos, permite la coexistencia de versiones antiguas y nuevas para que los clientes puedan migrar a su propio ritmo.

Por que es necesario: Cuando publicas una API, muchos clientes dependen de ella. Los cambios repentinos pueden romper las aplicaciones cliente y danar la confianza.

Que son los Cambios Disruptivos

Los siguientes tipos de cambios pueden romper el funcionamiento de los clientes existentes.

Ejemplos de Cambios Disruptivos

Ejemplos de Cambios No Disruptivos

• Adicion de nuevos campos opcionales
• Adicion de nuevos endpoints
• Adicion de nuevos parametros opcionales

Metodos de Versionado

1. Versionado por Ruta URL

GET /api/v1/users
GET /api/v2/users

Ventajas:

• Claro e intuitivo
• Facil de cachear
• Facil de probar desde el navegador

Desventajas:

• Algunos argumentan que viola los principios REST porque la URI cambia
• La URI del recurso no es fija

Ejemplos de uso: GitHub API, Twitter API, Stripe API

2. Versionado por Encabezado

GET /api/users
Accept: application/vnd.myapi.v1+json

O

GET /api/users
X-API-Version: 1

Ventajas:

• URI limpia
• Cumple con el estandar de negociacion de contenido

Desventajas:

• Dificil de probar desde el navegador
• Documentacion menos clara

Ejemplos de uso: GitHub API (parcialmente)

3. Versionado por Parametro de Consulta

GET /api/users?version=1
GET /api/users?version=2

Ventajas:

• Facil implementacion
• Facil establecer version por defecto

Desventajas:

• Facil olvidar el parametro
• Requiere consideracion de cache

Ejemplos de uso: Google APIs (parcialmente)

Tabla Comparativa

Mejores Practicas de Estrategia de Versionado

1. Evitar el Versionado Siempre que sea Posible

// Diseno extensible
// Agregar nuevos campos no afecta a los clientes existentes
{
  "name": "Alice",
  "email": "alice@example.com",
  // Agregar nuevo campo
  "profile": {
    "bio": "Developer"
  }
}

2. Proceso de Deprecacion

# Notificar deprecacion mediante encabezados de respuesta
Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"

3. Establecer Periodo de Migracion

4. Publicar Historial de Cambios

## Changelog

### v2.0.0 (2024-06-01)
**Breaking Changes:**
- Se dividio `user.name` en `user.firstName` y `user.lastName`
- Se cambio el formato de respuesta de `GET /users/:id/posts`

**Migration Guide:**
- Si esta usando el campo `name`, cambie a `firstName + ' ' + lastName`

Tecnicas para Mantener la Compatibilidad

Agregar Campos es Seguro

// v1
{ "id": 1, "name": "Alice" }

// v1.1 - Los clientes existentes ignoran el nuevo campo
{ "id": 1, "name": "Alice", "email": "alice@example.com" }

Campos Nullable y Valores por Defecto

// Nuevos campos son nullable o tienen valores por defecto
{
  "id": 1,
  "name": "Alice",
  "nickname": null,  // Opcional
  "isActive": true   // Valor por defecto
}

Patron Envelope

// Envolver la respuesta asegura extensibilidad
{
  "data": { "id": 1, "name": "Alice" },
  "meta": { "version": "1.0", "requestId": "abc123" }
}

Resumen

El versionado de API es una estrategia importante para equilibrar la evolucion de la API con la estabilidad de los clientes. El versionado por ruta URL es el mas comun y claro, pero seleccione el metodo apropiado segun los requisitos del proyecto. Lo mas importante es esforzarse por un diseno altamente extensible que minimice la necesidad de versionado.