Deoarece serviciile sunt implementate independent, nu poți niciodată presupune că apelatorii se actualizează sincron. Versionarea API plus compatibilitate cu versiunile anterioare permite producătorilor să evolueze fără a rupe consumatorii existenți.
| Strategie | Exemplu |
|---|
| Cale URI | GET /v2/orders/42 |
| Antet | Accept: application/vnd.api.v2+json |
| Evoluția schemei | adaugă câmpuri, nu elimina/redenumește niciodată |
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
}
Numerele de câmp, nu numele, definesc formatul de transport, deci adăugarea câmpurilor este compatibilă cu versiunile anterioare.
Release v2 ─▶ run v1 + v2 together ─▶ migrate consumers ─▶ deprecate v1 ─▶ remove v1
Nu elimina niciodată o versiune în timp ce traficul real o mai folosește. Urmărește utilizarea înainte de pensionare.
Implementabilitatea independentă funcționează doar dacă un producător poate livra o modificare fără a coordona lansarea fiecărui consumator.
Proiectarea pentru modificări aditive și sprijinul versiunilor vechi în timpul migrării este ceea ce preservă această independență în loc să forțeze actualizări fragile de tip big-bang.