Koska palvelut otetaan käyttöön itsenäisesti, et voi koskaan olettaa, että kutsujat päivittyvät synkronoidusti. API-versionointi sekä taaksepäin yhteensopivuus antavat tuottajille mahdollisuuden kehittyä rikkoutumatta olemassa olevia kuluttajia.
Koska palvelut otetaan käyttöön itsenäisesti, et voi koskaan olettaa, että kutsujat päivittyvät synkronoidusti. API-versionointi sekä taaksepäin yhteensopivuus antavat tuottajille mahdollisuuden kehittyä rikkoutumatta olemassa olevia kuluttajia.
| Strategia | Esimerkki |
|---|
| URI-polku | GET /v2/orders/42 |
| Otsikko | Accept: application/vnd.api.v2+json |
| Rakenteen kehitys | lisää kenttiä, älä koskaan poista/nimeä uudelleen |
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
}
Kentän numerot, ei nimet, määrittävät johtoliikenteen muodon, joten kenttien lisääminen on taaksepäin yhteensopivaa.
Release v2 ─▶ run v1 + v2 together ─▶ migrate consumers ─▶ deprecate v1 ─▶ remove v1
Älä koskaan poista versiota, kun oikea liikenne käyttää sitä silti. Seuraa käyttöä ennen eläkkeelle jäämistä.
Itsenäinen käyttöönottokelpoisuus toimii vain, jos tuottaja voi lähettää muutoksen koordinoimatta jokaisen kuluttajan julkaisua.
Additiiivisen muutoksen suunnittelu ja vanhojen versioiden tuki siirtymisen aikana on se, mikä säilyttää tämän itsenäisyyden sen sijaan, että pakotettaisiin hauraita kokonaisuudistuksia.