Compatibilidad de API y actualizaciones

1) Principios básicos de interoperabilidad

Additive-first: añadir uno nuevo sin romper el antiguo (nuevos campos/endpoints opcionales, nuevos valores enum).
Contratos estables: «lo prometido en la especificación es lo que funciona»; el comportamiento está documentado.
Backward> Forward: prioridad de compatibilidad retroactiva; forward está permitido a través de tolerant-readers.
Los documentos son primarios: la única fuente de verdad es la versión del esquema en el registro (OpenAPI/AsyncAPI/Proto).
Una clara evolución: el breaking es solo a través de la nueva versión mayor y guía migratoria.

2) Taxonomía de cambios

2. 1 Compatible (MINOR/PATCH)

Añadir campos/headers opcionales, nuevos endpoints, parámetros de query con impagos.
Aumentar los límites ('page _ size', TTL), aclarar errores sin cambiar códigos/semántica.
Agregar valores de enum si los clientes ignoran los «desconocidos» (tolerant-reader).

2. 2 Ambiguos (Behavioral)

Cambiar los impagos, el orden de clasificación, los temporizadores sutiles, las cuotas... puede «romper» la lógica empresarial. Requiere RFC + anuncio y Canarias.

2. 3 Rompiendo (MAYOR)

Cambio de nombre/eliminación de campos, cambio de tipo/formato, sustitución de códigos de error, incompatibilidad inversa de contratos/esquemas de autenticación.

3) Política de versionamiento

Estrategia: 'path versioning' ('/v1 ', '/v2').
Menor/parche: «añadir, no romper».
Encabezados fechados (dop.): 'X-API-Version-Date' para cambios graduales suaves.
Tipos de medios (ops.) : `Accept: application/vnd. acme. v1 + json 'para granulación fina.

4) Depresiones y sunset

4. 1 Títulos de comunicación

Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"

4. 2 Orden de salida

1. Anuncio en el portal/boletín/notas SDK release.
2. Ventana de advertencia ≥ 90-180 días.
3. Estados en dashboard adoption.
4. Después de sunset - 410 Gone o modo «read-only» para el período de grace, si se acuerda.

5) Migración y coexistencia de versiones

Dual-write/dual-read durante el período de transición e informes de conciliación.
Adaptadores (temporales): transformaciones de gateway de payload antiguos → nuevos esquemas; la vida útil del adaptador es limitada.
Asistencia SDK: versiones que admiten ambas versiones, con alertas de depreciación (1 vez por proceso).
Banderas de fichas: inclusión de una nueva semántica sobre la lista de claves/tenantes.

6) Backward y forward compatibilidad

6. 1 Backward (clientes antiguos ↔ nuevo servidor)

No cambiar los formatos de tipo/obligatoriedad.
Los nuevos campos son sólo opcionales.
Los errores son los anteriores 'error _ code', los nuevos códigos añadir, no reemplazar.

6. 2 Forward (nuevos clientes ↔ antiguo servidor)

Comprobar la disponibilidad de capacidades (capabilities) a través de 'OPTIONS '/'/versions'.
Comportamiento Grace: el cliente debe tolerar las fichas faltantes.

7) Contratos e inspecciones automáticas

Registro: almacena versiones de esquemas; Los diphs de PR → los informes de «breaking/non-breaking».
Linter: nombres/tipos, idempotencia, paginación, códigos estables.
CDC (Consumer-Driven Contracts): pruebas de integradores en el CI del proveedor (Aprox y análogos).
Puerta: PR se bloquea cuando se rompe sin 'bump mayor '/RFC.

yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml

8) Liberación canaria y retroceso

Canario: 10% → 25% → 50% → 100% de tráfico; retroceso automático en el deterioro de SLO (5xx/latency/429).
Claves Beta: acceso a nuevas versiones a través de allowlist.
Release freeze: cuando se quema error-budget.
Análisis de aceptación: proporción de tráfico/clientes en la nueva versión, tiempo de migración.

9) Compatibilidad en detalles: errores, paginación, idempotencia

9. 1 Errores

No cambie los estados HTTP en las secuencias de comandos existentes.
'error _ code' - estable; sólo añadir nuevos códigos.
'application/problem + json' es un formato único.

9. 2 Paginación

Cambiar a cursor/keyset = MINOR si se admite el antiguo 'offset/limit'.
Documente la clasificación de '(updated_at,id)' y la estabilidad del cursor.

9. 3 Idempotency

Para escribir - 'Idempotency-Key' + '409 IDEMP_REPLAY' en conflicto.
Las migraciones no deben cambiar la semántica de la idempotencia.

10) Transformación de Gateway (cuando corresponda)

Mapa v1→v2 campos, normalizar errores, convertir formatos de fecha/dinero.
Guardrails: las transformaciones son transparentes y lógicas; no esconda el breaking, sino que utilice como un puente de duración limitada.

11) Comunicaciones y Portal

Changelog с датами (`added/changed/deprecated/removed/fixed`).
Tarjeta de versión: estado (beta/GA/deprecated), fecha sunset, referencias a gaidas.
Webhooks de notificaciones: 'deprecation. notice`, `version. released`, `plan. change`.
SDK release notes + banner en el portal.

12) Métricas de éxito

Adoption rate v2 (según solicitudes/clientes).
Backward-compat incidentes (cole-in «rompimiento»).
Error mix (share 4xx/5xx/429) antes/después del lanzamiento.
Time-to-Adapt mediana.
Support load (tickets/ned).
Costo al servicio (costo de infraestructura por llamada).

13) Plantillas y ejemplos

13. 1 Títulos de versiones y deprecaciones

X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"

13. 2 Política de versiones (fragmento YAML)

yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]

13. 3 OpenAPI: adición compatible del campo

yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive

14) Lista de comprobación de lanzamiento (MINOR/MAJOR)

MINOR

• DIFF: no breaking, linter verde
• Documentación/SDK actualizada (ejemplos/codecs)
• Canario + retroceso automático por SLO
• Plan de Comm, página en el portal
• Dashboards adoption y errores

MAJOR

• RFC/ADR, fecha sunset y ventana ≥90 -180 días
• Puente v1↔v2 (gateway) y guía migratoria
• Dual-escritura/lectura y conciliación
• SDK con ambas API + alertas
• Piloto con integradores clave

15) Plan de implementación (3 iteraciones)

1. Fundación (2 semanas):

Registry esquemas, lentes y auto-diff en CI; Política de compatibilidad; encabezados 'Deprecation/Sunset'.

2. Versiones administradas (3-4 semanas):

Canarios, banderas ficha, alertas SLO; portal de versiones; Versiones SDK con soporte para 2 ramas.

3. Automatización y escala (continua):

Pruebas de consumo de CDC en CI, pronóstico de sunset sobre tendencias de adopción, notificaciones automáticas y recordatorios.

16) Mini preguntas frecuentes

¿Se puede cambiar el tipo de campo sin mayor?
No. Incluso «stroka→chislo» - breaking. Escriba un campo nuevo, antiguo - deprecate.

Enum: ¿puedo agregar valores?
Sí, si los clientes son tolerantes-lectores. De lo contrario, primero alerta y beta.

¿Cuánto tiempo guardaré la versión antigua?
Por ahora, la adopción del nuevo ≥95% y la ventana de deprecación se ha mantenido. Fije el plazo en la política.

La compatibilidad de la API es una disciplina: enfoque additive, esquemas formales y diphs, lanzamientos canarios, deprecaciones claras y migraciones gestionadas. Afianzar la política de cambio, automatizar las verificaciones y las comunicaciones, medir la adaptación - y sus actualizaciones dejarán de romper los clientes, y la velocidad de evolución aumentará sin perder confiabilidad.