Kako versionirati API-je i zadržati kompatibilnost unazad između usluga?

Question

Accepted Answer

Budući da se usluge implementiraju neovisno, nikada ne možete pretpostaviti da se pozivaoci ažuriraju u skladu. **Verzioniranje API-ja** plus **kompatibilnost unazad** omogućuje proizvođačima da se razvijaju bez prekidanja postojećih potrošača.

## Strategije verzioniranja

| Strategija | Primjer |
|---|---|
| URI putanja | `GET /v2/orders/42` |
| Zaglavlje | `Accept: application/vnd.api.v2+json` |
| Evolucija sheme | dodaj polja, nikad ne uklanjaj/preimenuj |

## Radije koristite aditivne (ne-prekidajuće) promjene

```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 prikladan za ovo

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

Brojevi polja, a ne imena, definiraju format žice, pa je dodavanje polja kompatibilno unazad.

## Životni ciklus

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

## Zamka

Nikada ne uklanjajte verziju dok je pravi promet još uvijek koristi. Pratite upotrebu prije povlačenja.

## Zašto je to važno

Neovisna implementabilnost funkcionira samo ako proizvođač može poslati promjenu bez usklađivanja izdanja svakog potrošača.

Dizajniranje za aditivne promjene i podrška starim verzijama tijekom migracije je ono što čuva tu neovisnost umjesto da forsira krhke cjelokupne nadogradnje.

URI putanja	`GET /v2/orders/42`
Zaglavlje	`Accept: application/vnd.api.v2+json`
Evolucija sheme	dodaj polja, nikad ne uklanjaj/preimenuj