7 min lectura • Guide 850 of 877
Estrategias de Versionado de API
Las estrategias de versionado de API aseguran una evolución suave de las APIs mientras mantienen compatibilidad. GitScrum ayuda a los equipos a rastrear cambios de API, decisiones de versionado y migración de clientes a través de ciclos de desarrollo.
Ciclo de Vida del Versionado
CICLO DE VIDA DE VERSIÓN DE API:
┌─────────────────────────────────────────────────────────────┐
│ │
│ Diseñar ──► Implementar ──► Planear ──► Lanzar ──► │
│ API v1 Cambios v2 │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ Requisitos Primera Análisis de Actualizaciones │
│ y Diseño Release & Breaking Backward │
│ Documentación Changes Compatible │
│ │
│ ──► Deprecar ──► Remover │
│ v1 v1 │
│ │ │ │
│ ▼ ▼ │
│ Período Fin de │
│ Sunset & Vida │
│ Migración Comunicación │
│ │
│ DURACIONES TÍPICAS: │
│ ──────────────────── │
│ • v1 activa: 12-24 meses │
│ • Período de overlap (v1 + v2): 6-12 meses │
│ • Sunset warning: 3-6 meses antes de remover │
│ • Deprecation notice: Header + documentación │
└─────────────────────────────────────────────────────────────┘
Estrategias de Versionado
Comparación de Enfoques
ENFOQUES DE VERSIONADO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ 1. VERSIONADO EN URI (Recomendado) │
│ ──────────────────────────────────── │
│ /api/v1/users │
│ /api/v2/users │
│ │
│ ✅ Claro y explícito │
│ ✅ Fácil de cachear (diferentes URLs) │
│ ✅ Fácil de debuggear en logs │
│ ✅ Simple de entender para consumidores │
│ ❌ Múltiples URLs para mismo recurso │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ 2. VERSIONADO POR HEADER │
│ ───────────────────────── │
│ Accept: application/vnd.api.v1+json │
│ Accept-Version: v1 │
│ X-API-Version: 2 │
│ │
│ ✅ URLs limpias │
│ ✅ Separación de concerns │
│ ❌ Menos visible │
│ ❌ Más difícil de probar en browser │
│ ❌ Puede olvidarse de enviar header │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ 3. QUERY PARAMETER │
│ ────────────────── │
│ /api/users?version=1 │
│ /api/users?v=2 │
│ │
│ ✅ Flexible │
│ ✅ Fácil de agregar │
│ ❌ Menos RESTful │
│ ❌ Puede confundirse con otros params │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ 4. MEDIA TYPE │
│ ───────────── │
│ application/vnd.company.resource.v2+json │
│ │
│ ✅ Semánticamente correcto │
│ ✅ Granularidad por recurso │
│ ❌ Más complejo de implementar │
│ ❌ Menos intuitivo │
└─────────────────────────────────────────────────────────────┘
Breaking Changes
Identificando Breaking Changes
¿QUÉ ES UN BREAKING CHANGE?
┌─────────────────────────────────────────────────────────────┐
│ │
│ 🔴 BREAKING (Requiere nueva versión): │
│ ──────────────────────────────────── │
│ • Remover campo de response │
│ • Renombrar campo │
│ • Cambiar tipo de dato de campo │
│ • Cambiar estructura de response │
│ • Remover endpoint │
│ • Cambiar URL de endpoint │
│ • Agregar campo requerido a request │
│ • Cambiar código de status para mismo caso │
│ • Cambiar formato de autenticación │
│ │
│ 🟢 NO BREAKING (Compatible, NO requiere nueva versión): │
│ ──────────────────────────────────────────────────────── │
│ • Agregar campo opcional a request │
│ • Agregar campo a response │
│ • Agregar nuevo endpoint │
│ • Agregar nuevo valor a enum (si cliente tolera) │
│ • Corregir bug (comportamiento documentado) │
│ • Mejorar mensajes de error │
│ │
│ PRINCIPIO POSTEL: │
│ ───────────────── │
│ "Sé conservador en lo que envías, │
│ liberal en lo que aceptas." │
│ │
│ Clientes deben ignorar campos desconocidos. │
│ Servidores deben ser tolerantes con input. │
└─────────────────────────────────────────────────────────────┘
Proceso de Deprecación
Timeline de Deprecación
PROCESO DE DEPRECACIÓN:
┌─────────────────────────────────────────────────────────────┐
│ │
│ FASE 1: ANUNCIO (Mes 0) │
│ ──────────────────────── │
│ • Comunicar deprecación a consumidores │
│ • Agregar a changelog y release notes │
│ • Actualizar documentación con warnings │
│ • Agregar header: Deprecation: true │
│ • Agregar header: Sunset: Sat, 1 Jan 2025 00:00:00 GMT │
│ │
│ FASE 2: MIGRACIÓN (Meses 1-6) │
│ ───────────────────────────── │
│ • Proporcionar guía de migración detallada │
│ • Ofrecer soporte para migración │
│ • Trackear uso de versión vieja │
│ • Enviar recordatorios periódicos │
│ │
│ FASE 3: WARNING ACTIVO (Mes 7-9) │
│ ───────────────────────────────── │
│ • Emails directos a usuarios restantes │
│ • Warning en dashboard de consumidores │
│ • Reducir rate limits en versión vieja (opcional) │
│ │
│ FASE 4: SUNSET (Mes 10) │
│ ───────────────────────── │
│ • Remover versión vieja │
│ • 410 Gone para requests a versión removida │
│ • Redirect o mensaje explicativo │
│ │
│ HEADERS DE DEPRECACIÓN: │
│ ──────────────────────── │
│ HTTP/1.1 200 OK │
│ Deprecation: true │
│ Sunset: Sat, 31 Dec 2024 23:59:59 GMT │
│ Link: </docs/migration-v2>; rel="deprecation" │
└─────────────────────────────────────────────────────────────┘
Versionado Semántico
SemVer para APIs
VERSIONADO SEMÁNTICO (SemVer):
┌─────────────────────────────────────────────────────────────┐
│ │
│ FORMATO: MAJOR.MINOR.PATCH │
│ Ejemplo: 2.3.1 │
│ │
│ MAJOR (2.x.x): │
│ ─────────────── │
│ Incrementar cuando: │
│ • Breaking changes │
│ • Cambios incompatibles con versión anterior │
│ Ejemplo: v1 → v2 │
│ │
│ MINOR (x.3.x): │
│ ─────────────── │
│ Incrementar cuando: │
│ • Nueva funcionalidad (backward compatible) │
│ • Nuevos endpoints │
│ • Nuevos campos opcionales │
│ Ejemplo: 1.2 → 1.3 │
│ │
│ PATCH (x.x.1): │
│ ─────────────── │
│ Incrementar cuando: │
│ • Bug fixes │
│ • Mejoras de documentación │
│ • Cambios internos sin impacto en API │
│ Ejemplo: 1.3.0 → 1.3.1 │
│ │
│ PARA APIs: │
│ ─────────── │
│ URL típicamente solo muestra MAJOR: /api/v2/ │
│ MINOR y PATCH en headers o documentación │
│ │
│ X-API-Version: 2.3.1 │
└─────────────────────────────────────────────────────────────┘
Gestión en GitScrum
Tracking de Versiones
ORGANIZACIÓN EN GITSCRUM:
┌─────────────────────────────────────────────────────────────┐
│ │
│ LABELS: │
│ ──────── │
│ [api-v1] [api-v2] [breaking-change] [deprecation] │
│ [migration] [backward-compatible] │
│ │
│ ÉPICAS POR VERSIÓN: │
│ ───────────────────── │
│ • API v2 Release │
│ ├── Nuevos endpoints │
│ ├── Breaking changes │
│ ├── Documentación │
│ └── Guía de migración │
│ │
│ • API v1 Deprecation │
│ ├── Comunicación a clientes │
│ ├── Tracking de uso │
│ ├── Soporte de migración │
│ └── Sunset y cleanup │
│ │
│ CUSTOM FIELDS: │
│ ─────────────── │
│ • API Version: v1 / v2 / v3 │
│ • Change Type: Breaking / Non-breaking │
│ • Migration Status: Not started / In progress / Complete │
│ │
│ DASHBOARD: │
│ ────────── │
│ • % de clientes migrados a v2 │
│ • Requests a v1 vs v2 (tracking uso) │
│ • Countdown a sunset de v1 │
│ • Issues de migración abiertos │
└─────────────────────────────────────────────────────────────┘