Saltar al contenido principal

Versionado

🎯 Objetivo​

Regla​

8.1: Se debe implementar una estrategia de versionado clara y consistente para gestionar los cambios en la API a lo largo del tiempo, minimizando el impacto en los clientes existentes. 8.2: La API debe permitir que diferentes versiones coexistan cuando se introducen cambios incompatibles (breaking changes).

📖 Concepto y Definición​

Regla​

8.3: El versionado de la API es obligatorio para gestionar la evolución del contrato de la API. 8.4: Un "cambio incompatible" (breaking change) es cualquier modificación en la API que pueda hacer que un cliente que dependía de la versión anterior falle o se comporte incorrectamente. Ejemplos:

  • Cambiar el formato de datos de una respuesta.
  • Eliminar o renombrar campos en una respuesta o solicitud.
  • Añadir un campo obligatorio a una solicitud.
  • Cambiar el tipo de dato de un campo.
  • Cambiar un código de estado HTTP esperado.
  • Eliminar un endpoint o un método HTTP de un endpoint.
  • Cambiar la semántica de una operación existente. 8.5: Los "cambios compatibles" (non-breaking changes) son aquellos que no deben romper la funcionalidad de los clientes existentes. Ejemplos:
  • Añadir un nuevo endpoint.
  • Añadir un nuevo método HTTP a un endpoint existente.
  • Añadir campos opcionales a una respuesta.
  • Añadir parámetros de consulta opcionales a una solicitud.
  • Añadir nuevos códigos de estado de error (que los clientes robustos deberían ignorar si no los esperan). 8.6: Se debe introducir una nueva versión de la API solo cuando se realicen cambios incompatibles (breaking changes). 8.7: Los cambios compatibles no deben requerir un incremento de la versión principal de la API.

Estrategia de Versionado Obligatoria:​

Regla​

8.8: El versionado debe realizarse exclusivamente a través de la URI, incluyendo el número de versión como un prefijo en la ruta base de la API.

  • Formato Obligatorio: /v<número> (ej. /v1, /v2).
  • Ejemplo Completo: https://api.example.com/v1/users, https://api.example.com/v2/users. 8.9: El número de versión debe ser un entero simple (1, 2, 3...). No se debe usar versionado semántico (ej. v1.2.3) en la URI. 8.10: Otros métodos de versionado (encabezados Accept, parámetros de consulta) están prohibidos para el versionado principal de la API debido a su menor visibilidad y potencial confusión.

🤔 ¿Por qué es Importante? / Beneficios Clave (Contexto)​

  • Estabilidad del Cliente: Clientes pueden seguir usando versiones antiguas.
  • Evolución Controlada: Permite introducir cambios incompatibles de forma segura.
  • Claridad: La versión es explícita en la URI.
  • Facilidad de Enrutamiento y Mantenimiento: Simplifica la gestión de diferentes versiones en el backend.

✅ Buenas Prácticas y Recomendaciones Clave​

Regla​

8.11: Se refuerza la Norma 8.8: El versionado debe hacerse vía URI con el formato /v<número>. 8.12: La versión v1 debe ser la versión inicial de la API pública. 8.13: Antes de introducir una nueva versión (ej. v2), se debe evaluar cuidadosamente si los cambios son realmente incompatibles. Se debe intentar mantener la compatibilidad hacia atrás siempre que sea posible para evitar la proliferación de versiones. 8.14: Al lanzar una nueva versión (vN), la versión anterior (v(N-1)) debe mantenerse operativa durante un período de deprecación razonable y comunicado. 8.15: Se debe establecer y comunicar claramente una política de ciclo de vida y deprecación para las versiones antiguas de la API, incluyendo:

  • El período de soporte para cada versión.
  • Las fechas de fin de soporte y retirada.
  • Instrucciones claras para la migración a la nueva versión. 8.16: La documentación de la API debe estar versionada junto con la API y ser fácilmente accesible para cada versión soportada. 8.17: El código base del servidor debe estar estructurado para facilitar el mantenimiento de múltiples versiones activas (ej. mediante módulos, ramas, o estrategias de despliegue específicas).

Don'ts (Prohibido):

  • 8.18: No se debe realizar un cambio incompatible en una versión existente de la API una vez publicada. Se debe crear una nueva versión.
  • 8.19: No se debe eliminar abruptamente una versión antigua sin un período de deprecación comunicado.
  • 8.20: No se debe usar el versionado en URI para cambios compatibles.
  • 8.21: No se debe usar otros métodos (encabezados, query params) para el versionado principal.
  • 8.22: No se debe usar versionado semántico (ej. /v1.1, /v1.2.3) en la URI de la API.

💡 Ejemplos Prácticos (Ilustrativos)​

Ejemplo 1: Introducción de un Cambio Incompatible​

  • API v1: GET /v1/users/{id} devuelve: 
    { "userId": 1, "name": "John Doe" }
  • Necesidad: Cambiar name a firstName y lastName. Esto es un cambio incompatible (Norma 8.4).
  • Solución Obligatoria: Introducir /v2.
  • API v2: GET /v2/users/{id} devuelve: 
    { "userId": 1, "firstName": "John", "lastName": "Doe" }
  • API v1 (/v1/users/{id}) debe seguir existiendo y funcionando durante el período de deprecación (Norma 8.14).

Ejemplo 2: Introducción de un Cambio Compatible​

  • API v1: GET /v1/products/{id} devuelve: 
    { "productId": "abc", "name": "Widget" }
  • Necesidad: Añadir una descripción opcional.
  • Solución Obligatoria: Modificar la respuesta de /v1.
  • API v1 (Modificada): GET /v1/products/{id} devuelve: 
    { "productId": "abc", "name": "Widget", "description": "A useful widget" }
    Esto no requiere /v2 porque el campo añadido es opcional y no rompe clientes existentes (Norma 8.5, 8.7).

Ejemplo 3: Deprecación Comunicada (Norma 8.15)​

  • La documentación y/o encabezados de respuesta para /v1 deben indicar su estado de deprecación y la fecha de retirada. 
    HTTP/1.1 200 OK
    Content-Type: application/json
    Warning: 299 - "API v1 is deprecated and will be removed on 2024-12-31. Please migrate to v2."
    // O un encabezado personalizado como `X-API-Deprecation-Status: deprecated; removal-date="2024-12-31"`

🛠️ Herramientas y Consideraciones Adicionales (Contexto)​

  • API Gateways: Pueden facilitar el enrutamiento de solicitudes a diferentes versiones del backend.
  • Documentación: Herramientas como Swagger/OpenAPI soportan la definición de múltiples versiones.
  • Comunicación: Es crucial comunicar los planes de versionado y deprecación a los consumidores de la API.