Parce que les services se déploient indépendamment, vous ne pouvez jamais supposer que les clients se mettent à niveau de manière synchronisée. Le versioning des API plus la compatibilité rétroactive permet aux producteurs d'évoluer sans casser les consommateurs existants.
| Stratégie | Exemple |
|---|
| Chemin URI | GET /v2/orders/42 |
| En-tête | Accept: application/vnd.api.v2+json |
| Évolution du schéma | ajouter des champs, jamais supprimer/renommer |
NON-BREAKING (safe):
✓ add a new optional field
✓ add a new endpoint
✓ add a new enum value (if clients tolerate unknowns)
BREAKING (needs a new version):
✗ remove or rename a field
✗ change a type or make a field required
✗ change semantics of an existing field
message Order {
string id = 1;
double total = 2;
string currency = 3; // NEW field 3 — old clients ignore it safely
}
Les numéros de champ, pas les noms, définissent le format de transmission, donc ajouter des champs est compatible rétroactivement.
Release v2 ─▶ run v1 + v2 together ─▶ migrate consumers ─▶ deprecate v1 ─▶ remove v1
Ne supprimez jamais une version tant que du trafic réel l'utilise encore. Suivez l'utilisation avant de la retirer.
La déployabilité indépendante ne fonctionne que si un producteur peut livrer un changement sans coordonner la version de chaque consommateur.
Créer une solution pour les changements additifs et supporter les anciennes versions pendant la migration est ce qui préserve cette indépendance au lieu de forcer des mises à jour fragiles et massives.