Compatibilité API et mises à jour
1) Principes de base de l'interopérabilité
Additive-first : ajoutez un nouveau sans casser l'ancien (nouveaux champs/endpoints optionnels, nouvelles valeurs enum).
Contrats stables : « Ce qui est promis dans le cahier des charges fonctionne » ; le comportement est documenté.
Backward> Forward : priorité de rétrocompatibilité ; forward est autorisé via tolerant-readers.
Les documents sont primaires : la seule source de vérité est la version du schéma dans le registre (OpenAPI/AsyncAPI/Proto).
Une évolution évidente : le breaking ne passe que par une nouvelle version major et un guide migratoire.
2) Taxonomie du changement
2. 1 Compatible (MINEUR/PATCH)
Ajoutez des champs/headers optionnels, de nouveaux endpoints, des paramètres query avec défaut.
Augmentation des limites ('page _ size', TTL), clarification des erreurs sans changement de code/sémantique.
Ajoute des valeurs enum si les clients ignorent les « inconnus » (tolerant-reader).
2. 2 Ambiguïté (Behavioral)
Modifier les défauts, l'ordre de tri, les délais subtils, les quotas - peut « briser » la logique d'entreprise. Nécessite RFC + annonce et canaries.
2. 3 Casseurs (MAJOR)
Renommer/supprimer les champs, modifier le type/format, remplacer les codes d'erreur, inverser l'incompatibilité des contrats/schémas d'authentification.
3) Politique de versioning
Stratégie : 'path versioning' ('/v1 ', '/v2').
Minor/patch : « ajoutez, ne cassez pas ».
Titres datés (dop.) : 'X-API-Version-Date' pour un léger changement progressif.
Types de médias (Opz.) : `Accept: application/vnd. acme. v1 + json 'pour la granulation fine.
4) Dépréciations et sunset
4. 1 Titres de communication
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"4. 2 Ordre de sortie
1. Annonce dans le portail/newsletter/SDK release notes.
2. Fenêtre d'avertissement ≥ 90-180 jours.
3. Statuts dans le dashboard d'adaptation.
4. Après sunset - 410 Gone ou « read-only » mode pour la période grace si convenu.
5) Migration et coexistence des versions
Dual-write/dual-read pendant la période de transition et rapprochement avec les rapports.
Adaptateurs (temporaires) : gateway-conversion d'anciens payload → de nouveaux schémas ; la durée de vie de l'adaptateur est limitée.
Aide SDK : versions supportant les deux versions, avec avertissements de dépréciation (1 fois par processus).
Ficha drapeaux : inclure une nouvelle sémantique sur la liste des clés/tenants.
6) Compatibilité Backward et forward
6. 1 Backward (anciens clients ↔ nouveau serveur)
Ne pas modifier les formats de type/obligatoire.
Les nouveaux champs ne sont qu'optionnels.
Erreurs - ancien 'error _ code', ajouter de nouveaux codes, ne pas remplacer.
6. 2 Forward (nouveaux clients ↔ ancien serveur)
Vérifiez les possibilités (capabilities) via 'OPTIONS '/'/versions'.
Comportement grace : le client doit tolérer les fiches manquantes.
7) Contrats et contrôles automatiques
Registry : nous stockons les versions des schémas ; Les diphes PR → les rapports « breaking/non breaking ».
Linter : noms/types, idempotence, pagination, codes stables.
CDC (Consumer-Driven Contracts) : tests des intégrateurs dans le CI du fournisseur (Pact et analogues).
Gate : PR est bloqué lors du breaking sans 'major bump '/RFC.
yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml8) Sortie canarique et marche arrière
Canary : 10 % → 25 % → 50 % → 100 % du trafic ; auto-recule en cas de détérioration du SLO (5xx/latency/429).
Clés bêta : accès aux nouvelles versions par allowlist.
Release freeze : lors de la combustion error-budget.
Analyse d'acceptation : part du trafic/clients sur la nouvelle version, temps de migration.
9) Compatibilité dans le détail : erreurs, pagination, idempotence
9. 1 Erreurs
Ne pas modifier les statuts HTTP dans les scripts existants.
'error _ code 'est stable ; ajouter de nouveaux codes.
'Application/problème + json 'est un format unique.
9. 2 Pagination
Passe à cursor/keyset = MINOR si l'ancien 'offset/limit' est pris en charge.
Documenter le tri '(updated_at,id)' et la stabilité du curseur.
9. 3 Idempotency
Pour write - 'Idempotency-Key' + '409 IDEMP_REPLAY' en cas de conflit.
Les migrations ne doivent pas changer la sémantique de l'idempotence.
10) Gateway-transformation (le cas échéant)
Map v1→v2 les champs, normaliser les erreurs, convertir les formats date/argent.
Guardrails : les transformations sont transparentes et logiques ; ne cachez pas le breaking, mais utilisez-le comme pont à durée limitée.
11) Communications et portail
Changelog с датами (`added/changed/deprecated/removed/fixed`).
Carte de version : statut (beta/GA/deprecated), date sunset, références aux hydes.
Notifications Web : 'deprecation. notice`, `version. released`, `plan. change`.
SDK release notes + bannière dans le portail.
12) Les métriques du succès
Adoption rate v2 (sur demande/clients).
Backward-compat incidents (kol-to « casser »).
Error mix (parts 4xx/5xx/429) avant/après la sortie.
Time-to-Adopt médian.
Charge de support (tickets/ned).
Cost-to-Serve (coût d'infrastructure par appel).
13) Modèles et exemples
13. 1 Titres des versions et dépressions
X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"13. 2 Stratégie de version (fragment 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 : Ajout de champ compatible
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+" } # additive14) Chèque de libération (MINEUR/MAJEUR)
MINOR
- DIFF : non breaking, linter vert
- Documentation/SDK mis à jour (exemples/codecs)
- Canaria + auto-retour sur SLO
- Com-plan, page dans le portail
- Dashboards d'adaptation et d'erreurs
MAJOR
- RFC/ADR, sunset date et fenêtre ≥90 -180 jours
- Pont v1↔v2 (passerelle) et guide des migrations
- Double-écriture/lecture et rapprochement
- SDK avec les deux API + alertes
- Pilote avec des intégrateurs clés
15) Plan de mise en oeuvre (3 itérations)
1. Fondation (2 semaines) :
Registry schémas, lint et auto-diff dans CI ; la politique d'interopérabilité ; les titres « Deprection/Sunset ».
2. Versions gérées (3-4 semaines) :
Canaries, drapeaux de ficha, alertes SLO ; le portail des versions ; Versions SDK avec prise en charge de 2 branches.
3. Automatisation et échelle (en continu) :
Les tests CDC des consommateurs en CI, les prévisions sunset sur les tendances d'adaptation, les notations automatiques et les rappels.
16) Mini-FAQ
Puis-je changer le type de champ sans majeur ?
Non. Même « stroka→chislo » - breaking. Entrez un nouveau champ, l'ancien est deprecate.
Enum : Puis-je ajouter des valeurs ?
Oui, si les clients sont des lecteurs tolérants. Sinon, d'abord l'alerte et bêta.
Combien tenir l'ancienne version ?
Jusqu'à présent, addition de la nouvelle ≥95 % et la fenêtre de dépréciation est maintenue. Fixez un délai dans la politique.
Résultat
L'interopérabilité des API est une discipline : approche additive, schémas formels et diphes, sorties canaries, dépressions claires et migrations gérables. Fixez une politique de changement, automatisez les vérifications et les communications, mesurez l'option - et vos mises à jour arrêteront de briser les clients et la vitesse d'évolution augmentera sans perte de fiabilité.