Kako verzioniraš API-je in ohraniš nazaj kompatibilnost med storitvami?

Question

Accepted Answer

Ker se storitve uvajajo neodvisno, nikoli ne moreš predpostaviti, da se klicatelji posodabljajo sočasno. **Verzioniranje API-jev** in **nazaj kompatibilnost** omogočata proizvajalcem razvoj brez kršitve obstoječih potrošnikov.

## Strategije verzioniranja

| Strategija | Primer |
|---|---|
| URI pot | `GET /v2/orders/42` |
| Glava | `Accept: application/vnd.api.v2+json` |
| Evolucija sheme | dodaj polja, nikoli ne briši/preimenuj |

## Prednost aditivnih (ne-prekinjenih) sprememb

```text
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
```

## Protobuf je prijazen temu

```proto
message Order {
  string id = 1;
  double total = 2;
  string currency = 3;  // NEW field 3 — old clients ignore it safely
}
```

Številke polj, ne imena, določajo žični format, zato je dodajanje polj nazaj kompatibilno.

## Življenjski cikel

```text
Release v2 ─▶ run v1 + v2 together ─▶ migrate consumers ─▶ deprecate v1 ─▶ remove v1
```

## Napaka

Nikoli ne umaknite verzije, medtem ko je še vedno pravi promet. Spremljajte uporabo pred upokojanjem.

## Zakaj je to pomembno

Neodvisna uvajanje deluje le, če lahko proizvajalec pošlje spremembo brez usklajevanja izdaje vsakega potrošnika.

Oblikovanje za aditivne spremembe in podpora starih verzij med migracijo je tisto, kar ohrani to neodvisnost namesto prisiljevanja krhkih nadgradenj v eni potezi.

URI pot	`GET /v2/orders/42`
Glava	`Accept: application/vnd.api.v2+json`
Evolucija sheme	dodaj polja, nikoli ne briši/preimenuj