Stratégies de versioning API

Pourquoi le versioning est nécessaire

L'API change plus rapidement que les clients. Le versioning permet de produire des fiches et de réguler les erreurs sans rupture d'intégration, définit un rituel de changement et rend l'évolution prévisible. Clé : modifications additives par défaut, majors uniquement pour les tranches, contrôles de compatibilité automatiques et stratégie de sunset réfléchie.

Principes de base

1. Additive-first : nouveaux champs/méthodes/événements optionnels - ok ; les suppressions et les changements de sens sont majeurs.
2. Le MGC (contrat minimum de garantie) est stable ; enrichissement - par capabilities/' ? include = '.
3. Lecteur Tolérant : les clients ignorent les champs inconnus et vivent correctement les extensions enum.
4. Semantic Versioning: `MAJOR. MINOR. PATCH'pour artefacts, SDK et événements.
5. Automate : schema-diff, linters et tests CDC bloquent les changements de breaking.

Où stocker la version (mécanique d'adressage)

REST/HTTP

Version URI : '/v1/orders '→ simple à acheminer, pratique dans les passerelles. Moins - « obscurcit » l'évolution des perceptions.
Médiatip/titre : 'Accept : application/vnd. example. orders. v1 + json '- contrôle précis du format ; c'est plus difficile de débiter.
Version query : '? api-version = 1' - pratique pour A/B, mais facile à perdre dans les caches/logs.
Recommandation : URI pour les lignes majeures + feature/capability flags et negaciation de contenu pour les extensions mineures.

gRPC / Protobuf

Packages/services : 'package payments. v1; services PaymentsV1 ; '- lignes explicites.
La numérotation des étiquettes est inchangée ; les balises supprimées ne sont pas réutilisées.
Les nouveaux champs sont 'optional' ; breaking → nouveau '.v2'.

GraphQL

Schéma sans majeur explicite dans l'URL. Évolution via @ deprecated et fenêtres de migration ; le « vrai » major est un nouveau schéma endpoint.
Contrôler la complexité/depth fait partie du contrat.

Event-driven (Kafka/NATS/Pulsar)

Nom de l'événement : 'payment. authorized. v1 'est la version du type.
Registre des schémas (Avro/JSON Schema/Protobuf) avec modes de compatibilité (BACKWARD/FORWARD/FULL).
Major → dual-emit « v1 » et « v2 » pour une période transitoire.

Modèle de version et stratégie de modification

Semantic Versioning

MAJOR - Modifications brisantes : suppression/renommage des champs, changement de clés de lot, signification différente des statuts, renforcement de la validation.
MINOR - additif : nouveaux champs/endpoints/événements facultatifs, nouvelles valeurs enum sous tolerant-reader.
PATCH - corrections sans modification de contrat et de sémantique.

Deprecation & Sunset

Marquez l'obsolète ('Deprecated : true', '@ deprecated'), publiez la date sunset, l'alternative et l'hyde de migration.
Dans HTTP, les en-têtes « Sunset », « Deprection » ; dans les événements - un '.deprecation. notice`.
Utilisez la télémétrie pour prendre une décision de retrait.

Stratégies de version par style

REST

Lignes majeures sur/v1 ,/v2.
MINEUR : extension des schémas, '? fields =', '? include =' ; enum-extensions sûres.
ETag/If-Match et POST idempotent pour une cohérence sans cassure.
Les erreurs sont un format stable ('type', 'code', 'trace _ id').

gRPC

Introduisez de nouveaux services/méthodes pour les tranches : 'PaymentsV2. Capture`.
Les statuts d'erreur et la sémantique deadline font partie du contrat ; modification → nouvelle méthode/service.
Streaming : négociez l'ordre des messages et ne les changez pas en mineur.

GraphQL

Ajoutez des champs et des types librement ; suppression - via '@ deprecatated' + la fenêtre de migration ; une grande refonte → un nouveau schéma ('/graphql-v2 ').
Introspection et descriptions - must-have pour les migrations de clients.

Events

Core vs enriched : le noyau est stable, les enrichissements vivent côte à côte et sont convertis séparément.
La clé de lot est inchangée dans la ligne major.
Migration majeure - 'dual-emit' + migration de projections/consumers.

Negotiation et drapeaux capability

Capabilities : le client envoie 'X-Capabilities : risk_score,price_v2' ; le serveur répond par une vue étendue.
Prefer (HTTP) et « hints » pour les réponses partielles.
Dans les sockets/sticks, un message handshake avec une liste des extensions prises en charge.

Sortie des versions majeures sans douleur

1. RFC/ADR : Pourquoi le major, ce qui casse, la matrice des risques.
2. Dual-run : lancement parallèle de 'v1' et 'v2' (double publication d'événements, deux routes de passerelle, miroir de trafic).
3. Adaptateurs de migration : proxy/traducteurs 'v1↔v2' pour les clients lourds.
4. Canarica : par groupe de clients/tops/tags dans gateway.
5. Sunset-plan : dates, communication, stands, données de test, suivi de l'utilisation.

Rôle de la plate-forme et de l'infrastructure

API Gateway/Service Mesh : routage par version, en-têtes, chemins ; rate-limit и auth per-version.
Schema Registry & Catalogue : une source de vérité pour les spots/circuits avec une histoire de diffamation.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Observability : la version doit entrer dans les logs/trajets/métriques.

Tests de version

Schema-diff en PR : bloquer le breaking.
Contrats Consumer-Driven : le fournisseur est testé contre les contrats des vrais consommateurs.
Samples d'or : réponses de référence aux versions.
E2E-canari : comparaison p95/p99, erreurs et temporisations entre les versions.
Replay pour les événements : les projections se repositionnent en v2 sans divergence.

Migration de données et de bases

Pour REST/gRPC : les migrations OBD sont coordonnées via expand-and-contract (ajoutez une colonne → commencez à écrire → passez à la lecture → cassez l'ancienne).
Pour Events : double-emit et migration des consumers ; parfois, une reprise de la loge sur de nouvelles projections.
Ne faites pas de « grandes explosions » - divisez en pas avec des retours en arrière.

Relation avec la sécurité

Scopes per version : Différents OIDC-scopes/rôles pour v1/v2.
Les secrets/claim's token font partie du contrat ; leur changement = majeur.
PII/PCI - n'étendez pas payload inutilement ; nouveaux champs - avec un minimum de privilèges.

Anti-modèles

Swagger-wash : la spécification a été mise à jour, le serveur non (ou vice versa).
L'utilisation excessive des étiquettes protobuf est une corruption silencieuse des données.
Changement de sens enum sans majeur.
Global '/v2 '« pour les cosmétiques » : version sans le fait d'une rupture.
Oublié sunset/utilisation-métrique : impossible de retirer l'ancienne version en toute sécurité.
Un top commun pour différents majeurs : mélange d'ordres et de clés.

Chèque avant la sortie

• Les modifications sont additives ou une ligne majeure distincte a été préparée.
• Linters et schema-diff sont verts (breaking n'a pas survolé).
• Mis à jour SDK/exemples/documentation, notes de bas de page sur l'interopérabilité.
• Inclus dans le lecteur tolérant dans les clients ; enum-fallback testé.
• Pour major - plan dual-run, adaptateurs, canari, sunset-days et newsletter.
• Les métriques/logs/trajets contiennent une version et une segmentation par elle.
• Il y a un stand et des kits golden pour comparer les v1↔v2.
• Pour les événements - le registre des schémas en mode BACKWARD/FULL, les clés de lot sont inchangées.

Exemples de modèles

REST (URI + negotiation)

Itinéraire : '/api/v2/orders/{ id} '

Заголовок: `Prefer: include=items,customer`, `X-Capabilities: risk_score`

Deprecation: `Sunset: 2026-06-30`, `Link: ; rel="alternate"`

Protobuf/gRPC

proto package payments.v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

Events

`payment. captured. v2 '(noyau) et' payment. enriched. v2 '(détails).
Pour une période transitoire, le producteur est « v1 » et « v2 ».

FAQ

Quand as-tu besoin de « /v2 »?
Lorsque les invariants/sémantiques changent, les champs/méthodes sont supprimés, le format des identifiants, la clé de lot, les SLA/temporisations sont modifiés, de sorte que les clients se cassent.

Peut-on vivre sans version explicite dans REST ?
Seulement pour les petits systèmes. Pour les intégrations extérieures, les lignes majeures sont meilleures.

Quel délai pour garder une version obsolète ?
Cela dépend de l'écosystème. Pour les partenaires externes généralement 6-12 mois avec préavis et canari.

En quoi le versioning des événements diffère-t-il de l'API ?
Événements - append-only ; nouvelle sémantique = nouveau type '.v2' et dual-emit. La clé du lot fait partie du contrat.

Total

Les stratégies de versioning sont un processus et des outils : évolution additive par défaut, lignes majeures claires, capability-negotiation, dual-run et sunset. Ajoutez à cela les contrôles de compatibilité automatiques, la télémétrie d'utilisation et la discipline de la documentation - et vos API évolueront rapidement, sans « migrations nocturnes » et sans chutes inattendues chez les clients.