Compatibilité API contractuelle

Pourquoi l'interopérabilité contractuelle est-elle nécessaire ?

L'interopérabilité contractuelle est la capacité de l'API à évoluer sans casser les intégrations existantes. Dans les systèmes d'API en croissance, les codes clients changent plus souvent ; la compatibilité permet de produire des fiches itératives sans organiser de « gros déménagements ».

L'idée clé est que le contrat est primaire, les changements se déroulent selon les règles de compatibilité et sont vérifiés automatiquement.

Notions de base

Contrat - spécification formelle de l'interface : ressources/méthodes/événements, schémas de données, codes d'erreur, limites, SLA, exigences de sécurité.
Le fournisseur est le propriétaire de l'API. Consommateur (consumer) - client/intégration.

• Backward : le nouveau fournisseur travaille avec les anciens consommateurs.
• Forward : l'ancien fournisseur travaille avec de nouveaux consommateurs (généralement réalisé par des « lecteurs tolérants »).
• Full : backward et forward (l'option la plus forte).
• Additivité : Ajoute des éléments facultatifs sans casser les éléments existants.

Politique de versioning

• MAJOR - Modifications brisantes (uniquement lorsque la nouvelle ligne API est libérée : '/v2 ',' service. v2`).
• MINOR - Modifications additives (nouveaux champs/méthodes optionnels).
• PATCH - corrections sans modification de contrat.
• Politique de suppression : déclaration des éléments obsolètes, fenêtre de support (sunset), avertissements dans les titres/métadonnées, plan de retrait.

Sécurité vs changements dangereux

Sécurisé (généralement backward-compatible)

Ajoute un champ facultatif à JSON/Protobuf/Avro.
Ajout d'un nouvel endpoint/méthode/événement.
Extension d'enum avec de nouvelles valeurs si les consommateurs tolèrent des valeurs inconnues.
Augmenter les limites (par exemple, 'maxItems') sans durcir le minimum.
Ajoute nullable avec des défauts corrects.
Modifier le texte des descriptions/exemples.

Dangereux (briser la compatibilité)

Renommer/supprimer des champs, en modifier le type ou l'obligation.
Changement de sémantique des codes de statut/erreurs (par exemple, il y avait « 200 », il est devenu « 204 » ou « 404 »).
Modifie le format des identifiants (UUID → int).
Renforcement de la validation (plus strict que les minimums/modèles) sans version.
Modification de l'ordre et de la structure dans les strimes/événements gRPC.
Réutilisation des numéros d'étiquettes dans Protobuf pour les nouveaux champs.

Compatibilité par style d'interaction

REST/HTTP + JSON Schema

Additivité : les nouveaux champs sont marqués comme 'optional '/' nullable'.
Tolerant Reader chez le client : ignorer les champs inconnus ; ne pas compter sur l'ordre.
Versioning : majeur - en transit ('/v2 ') ou en médiatipe (' application/vnd. example. v2+json`).
ETag/If-Match : pour des mises à jour sécurisées sans course.
Erreurs : format unique ('type', 'code', 'titre', 'detail', 'trace _ id'), ne changez pas les valeurs de 'code' sans majeur.
Pagination : les curseurs sont préférés à offset ; ajoutez les champs 'next _ cursor', ne changez pas le sens des champs existants.

gRPC / Protobuf

La numérotation des balises est inchangée. Les balises supprimées ne sont pas réutilisées.
Les nouveaux champs sont 'optional '/' repeated' avec des défauts raisonnables sur le serveur.
Ne changez pas l'ordre et l'obligation des messages dans streaming-RPC.
Les états d'erreur sont stables ('INVALID _ ARGENT', 'FAILED _ PRECONDITION', etc.) ; nouvelle sémantique → nouvelle version de la méthode/service.

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

Nommage des événements : 'domain. action. v{major}`.
Les nouveaux champs sont facultatifs ; isoler le noyau et l'enrichissement ('.enriched').
Registres de schémas : règles d'interopérabilité (BACKWARD/FORWARD/FULL) par thème/événement.
L'extension enum est autorisée avec un lecteur tolérant du côté des consommateurs.
Changement de clé/ordre de lot pour l'agrégat = modifications cassantes.

GraphQL

Ajout de champs/types - sécurisé ; Supprimer/renommer uniquement via @ deprecated et la fenêtre de migration.
Ne changez pas de type/non nullable sans majeur.
Contrôlez la complexité/depth - les limites font partie du contrat.

Modèles d'évolution durable

Additive-first : étendre sans casser.
Capability negotiation : les clients déclarent qu'ils prennent en charge (en-têtes/paramètres/arrangements), le serveur s'adapte.
Limites du contrat : fixez le MGC (contrat minimum de garantie) et séparez les extensions (modèle de pyramide inverse).
Tolerance by default : les clients ignorent l'excès et gèrent correctement les valeurs inconnues d'enum (fallback).
Dual-write/Dual-emit : en cas de changements majeurs, sortez 'v1' et 'v2' en parallèle pendant un certain temps.
Sunset headers/Events : informez-vous à l'avance du retrait des versions.

Gouvernance et automatisation

• OpenAPI/Spectral : nommage, pagination, codes d'erreur, formats de champ.
• Buf/Protobuf : interdiction de réutiliser les étiquettes, notation des paquets.
• AsyncAPI/Schema Registry : compatibilité des schémas au niveau CI.
• Répertoire des contrats (SSOT) : registre centralisé des schémas/versions avec historique des diffs.
• API Guild : guilde/comité qui accepte les règles, les modèles et la révision des modifications.
• Gestion du changement : RFC/ADR, notes de sortie, hydes de migration.

Tests de compatibilité

Schema-diff dans CI : nous bloquons les modifications brisantes des spots (OpenAPI-diff, Buf breaking, SR compatibilité).
Contrats Consommateurs-Conducteurs (CDC) : Pact/similaires - vérification du fournisseur contre des contrats de consommateurs spécifiques.
Samples d'or : demandes de référence/réponses et événements pour la régression.
E2E Canary : Distribution par part de trafic/groupe consumer séparé.
Chaos/latency : vérification des délais/retraits - le changement de latency-SLO est considéré comme un changement de contrat.

Migrations et déprécation

1. Déclarez le deprecate : marquez l'élément, indiquez la date limite du sunset et l'alternative.
2. Maintenez la période de compatibilité : dual-write/dual-emit, ponts, adaptateurs.
3. Rassemblez la télémétrie : Qui d'autre utilise l'ancienne ?
4. Communication : bulletins d'information, notes de sortie, bancs d'essai.
5. Retrait : à l'expiration de la fenêtre - suppression avec une version fixe.

Exemples de changements

REST

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

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

Les clients qui ignorent les champs inconnus ne se cassent pas.

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 '(noyau) +' paiement. enriched. v1 '(enrichissement). Les consommateurs de la voie critique lisent le noyau et ne dépendent pas de l'enrichissement.

Anti-modèles

Swagger-wash : la spécification est formellement là, mais le comportement du service diverge avec elle.
Breaking by stealth : ont changé de type/statut/format sans nouvelle version et fenêtre de migration.
Les événements CDC bruts sont comme un contrat public : fuite de circuits OBD, impossibilité d'évolution.
Client dur : tombe à des champs/valeurs inconnus ; absence de lecteur tolérant.
Réutilisation des étiquettes protobuf : corruption silencieuse des données.
La latence est comme « non contractuelle » : soudainement allongé p95 - les consommateurs se brisent dans les temps.

Chèque de compatibilité (avant merge)

• Les modifications sont additives (ou une version majeure a été préparée).
• Les chèques linters/diff sont passés, les règles d'interopérabilité sont vertes.
• Les erreurs/codes/statuts n'ont pas changé la sémantique.
• Enum étendu sans interdire les anciennes valeurs ; les clients sont tolérants.
• Les limites de MGC sont inchangées.
• Exemples/documentation/SDK mis à jour.
• Pour le majeur - plan dual-write/dual-emit, sunset-date, comm-plan.
• Les tests ont CDC/Golden/E2E passés.

FAQ

En quoi backward diffère-t-il de la compatibilité forward ?
Backward - Les nouveaux serveurs ne brisent pas les anciens clients. Forward - Les nouveaux clients ne se cassent pas sur les anciens serveurs (par l'intermédiaire d'un lecteur tolérant et de défauts soignés).

Quand faire '/v2 'après tout ?
Lorsque les invariants/sémantiques changent, que les champs/méthodes sont supprimés, un nouveau modèle de sécurité est nécessaire - il est plus facile et plus honnête de démarrer une nouvelle ligne.

Est-il possible de vivre sans Schema Registry/Linters ?
En théorie, oui, c'est presque des régressions fréquentes et des éclats « cachés ». L'automatisation est rentable.

Enum peut-il être étendu ?
Oui, si les clients gèrent correctement des valeurs inconnues (fallback/ignore). Sinon, c'est un majeur.

Résultat

L'interopérabilité contractuelle est la règle + discipline + automatisation. Concevez de manière additive, versionnez les changements cassants, appliquez un lecteur tolérant, vérifiez automatiquement les diffs et les CDC, planifiez le déprécat. C'est ainsi que les API peuvent évoluer rapidement et que les intégrations peuvent rester stables.