Compatibilidad contractual con API

¿Por qué se necesita compatibilidad contractual?

La interoperabilidad contractual es la capacidad de la API para evolucionar sin romper las integraciones existentes. En los sistemas de API en crecimiento, cambian con más frecuencia el código de los clientes; la compatibilidad permite la producción de fiches de forma iterativa, sin conformarse con «grandes movimientos».

Idea clave: el contrato es primario, los cambios pasan por las reglas de compatibilidad y se comprueban automáticamente.

Conceptos básicos

Contrato - especificación formal de la interfaz: recursos/métodos/eventos, esquemas de datos, códigos de error, límites, SLA, requisitos de seguridad.
Proveedor: propietario de la API. Consumidor (consumer) - cliente/integración.

• Backward: el nuevo proveedor trabaja con consumidores antiguos.
• Forward: un viejo proveedor trabaja con nuevos consumidores (generalmente alcanzado por «lectores tolerantes»).
• Full: respetado tanto backward como forward (la opción más fuerte).
• Aditividad: agregue elementos opcionales sin romper los existentes.

Política de versionamiento

• MAJOR - Cambios rompedores (sólo cuando se lanza una nueva línea de API: '/v2 ',' servicio. v2`).
• MINOR - Cambios aditivos (nuevos campos/métodos opcionales).
• PARCHE - correcciones sin modificar el contrato.
• Política de depreciación: declarar elementos obsoletos, ventana de soporte (sunset), advertencias en encabezados/metadatos, plan de desactivación.

Cambios peligrosos seguros vs

Seguro (generalmente compatible con backward)

Agrega un campo opcional a JSON/Protobuf/Avro.
Agregar un nuevo endpoint/método/evento.
Extensión enum con nuevos valores si los consumidores son tolerantes a valores desconocidos.
Aumentar los límites (por ejemplo, 'maxItems') sin apretar los mínimos.
Agregar nullable con defectos correctos.
Cambiar el texto de las descripciones/ejemplos.

Peligroso (rompe la compatibilidad)

Renombrar/eliminar campos, cambiar su tipo o obligatoriedad.
Cambio de semántica de códigos de estado/errores (por ejemplo, hubo '200', se convirtió en '204' o '404').
Cambiar el formato de ID (UUID → int).
Apriete la validación (más estrictamente los mínimos/patrones) sin versión.
Cambio de orden y estructura en gRPC streams/eventos.
Vuelva a utilizar los números de etiqueta en Protobuf para nuevos campos.

Compatibilidad con estilos de interacción

REST/HTTP + JSON Schema

Aditividad: los nuevos campos se marcan como 'optional '/' nullable'.
Tolerant Reader en el cliente: ignorar campos desconocidos; no confiar en el orden.
Versioning: mayor - en el camino ('/v2 ') o en el mediatipo (' application/vnd. example. v2+json`).
ETag/If-Match: para apdates seguros sin carreras.
Errores: formato único ('type', 'code', 'title', 'detail', 'trace _ id'), no cambie los valores de 'code' sin mayor.
Paginación: los cursores son preferibles a offset; agregue los campos 'next _ cursor', no cambie el significado de los existentes.

gRPC / Protobuf

La numeración de etiquetas no cambia. No se pueden volver a utilizar las etiquetas eliminadas.
Los nuevos campos son 'optional '/' repeated' con incumplimientos razonables en el servidor.
No cambie el orden y la obligatoriedad de los mensajes en streaming-RPC.
Los estados de error son estables ('INVALID _ ARGUMENT', 'FAILED _ PRECONDITION', etc.); nueva semántica → nueva versión del método/servicio.

Event-driven (Kafka/NATS/Pulsar) + Avro/JSON Schema

Nomenclatura de eventos: 'domain. action. v{major}`.
Los nuevos campos son opcionales; resaltar el núcleo y el enriquecimiento ('.enriched').
Registros de esquemas: reglas de compatibilidad (BACKWARD/FORWARD/FULL) por tema/evento.
La extensión enum es admisible con un lector tolerante en el lado de los consumidores.
Cambio de la clave de lote/orden para el agregado = cambios rompedores.

GraphQL

Agregar campos/tipos - de forma segura; eliminación/cambio de nombre: sólo a través de @ deprecated y la ventana de migración.
No cambie de tipo/no nullable sin mayor.
Controle complexity/depth: los límites son parte del contrato.

Patrones de evolución sostenible

Additive-first: expandir sin romper.
Capability negotiation: los clientes informan que son compatibles (encabezados/parámetros/arreglos), el servidor se ajusta.
Límites del contrato: fijar el MGC (contrato de garantía mínima) y separar las extensiones (modelo de pirámide inversa).
Tolerance by default: los clientes ignoran el exceso y manejan correctamente los valores enum desconocidos (fallback).
Dual-write/Dual-emit: con cambios mayores, suelta 'v1' y 'v2' en paralelo durante un tiempo.
Sunset headers/Events: notifica con antelación la retirada de versiones.

Gobierno y automatización

• OpenAPI/Spectral: nomenclatura, paginación, códigos de error, formatos de campo.
• Buf/Protobuf: prohibición de volver a usar etiquetas, notación de paquetes.
• AsyncAPI/Schema Registry: compatibilidad de esquemas a nivel CI.
• Catálogo de contratos (SSOT): registro centralizado de esquemas/versiones con historial de diffs.
• API Guild: gremio/comité que acepta reglas, plantillas y revisiones de cambios.
• Gestión de cambios: RFC/ADR, notas de release, gaidas migratorias.

el Test de la compatibilidad

Schema-diff en CI: bloqueamos los cambios rompedores de spec (OpenAPI-diff, Buf breaking, SR compatibility).
Consumer-Driven Contracts (CDC): Nat/Afines - Validación del proveedor contra contratos específicos del consumidor.
Muestras de oro: consultas/respuestas de referencia y eventos de regresión.
E2E Canary: distribución de la parte del tráfico/grupos de consumer individuales.
Chaos/latency: chequeo de temporizadores/retraídos - el cambio latency-SLO se considera un cambio en el contrato.

Migraciones y depreciaciones

1. Declare el deprechate: marque el elemento, especifique la fecha límite del sunset y la alternativa.
2. Mantenga el período de compatibilidad: dual-write/dual-emit, puentes, adaptadores.
3. Recoge la telemetría: ¿quién más usa lo viejo?
4. Comunicación: boletines, notas de lanzamiento, stands de prueba.
5. Retirada: una vez que la ventana ha expirado, se elimina la versión fija.

Ejemplos de cambios

REST

json
{ "id":"p1", "status":"authorized" }

json
{ "id":"p1", "status":"authorized", "risk_score": 0. 12 }

Los clientes que ignoran campos desconocidos no se rompen.

Protobuf

proto message Payment {
string id = 1;
string status = 2; // don't change tag numbers optional double risk_score = 3; // additive
}

Event

`payment. authorized. v1 '(núcleo) +' pago. enriched. v1 '(enriquecimiento). Los consumidores de la vía crítica leen el núcleo y son independientes del enriquecimiento.

Antipattern

Swagger-wash: la especificación está formalmente ahí, pero el comportamiento del servicio está en desacuerdo con él.
Breaking by stealth: cambio de tipo/estado/formato sin nueva versión y ventana de migración.
Eventos crudos de los CDC como contrato público: filtración de esquemas de DB, imposibilidad de evolución.
Cliente duro: cae en campos/valores desconocidos; ningún tolerante reader.
Volver a usar las etiquetas protobuf: la corrupción silenciosa de los datos.
Latencia como «no contractual»: inesperadamente alargado p95 - los consumidores se rompen por los timautas.

Lista de verificación de compatibilidad (antes del merjem)

• Los cambios son aditivos (o la versión mayor está preparada).
• Se han pasado los cheques linters/diff, las reglas de compatibilidad son verdes.
• Los errores/códigos/estados no cambiaron la semántica.
• Enum se extienden sin prohibir los valores antiguos; clientes - tolerant.
• Los límites del MGC son invariables.
• Ejemplos/documentación/SDK actualizados.
• Para mayor - plan dual-write/dual-emit, sunset-date, plan comm.
• Las pruebas CDC/Golden/E2E superaron.

FAQ

¿En qué se diferencia la backward de la compatibilidad forward?
Backward: los nuevos servidores no rompen clientes antiguos. Forward - los nuevos clientes no se rompen en los servidores antiguos (a través de tolerant reader e impagos ordenados).

¿Cuándo hacer '/v2 '?
Cuando cambian las invariantes/semánticas, se eliminan los campos/métodos, se requiere un nuevo modelo de seguridad: es más fácil y honesto iniciar una nueva línea.

¿Es posible vivir sin Schema Registry/linters?
Teóricamente - sí, prácticamente - son frecuentes las regresiones y las roturas «ocultas». La automatización está dando sus frutos.

¿Se puede ampliar Enum?
Sí, si los clientes manejan correctamente valores desconocidos (fallback/ignore). De lo contrario, mayor.

La compatibilidad contractual es reglas + disciplina + automatización. Diseñe aditivamente, verifique los cambios rotos, aplique un lector de tolerantes, compruebe los diffs y los CDC de forma automática, planifique un deprechate. Así las APIs podrán evolucionar rápidamente y las integraciones podrán mantenerse estables.