Jak wersjonujesz API i utrzymujesz kompatybilność wsteczną na wszystkich usługach?

Question

Accepted Answer

Ponieważ usługi są wdrażane niezależnie, nigdy nie możesz założyć, że obiekty wywołujące uaktualniają się synchronicznie. **Wersjonowanie API** plus **kompatybilność wsteczna** pozwalają producentom ewoluować bez przerywania istniejących konsumentów.

## Strategie wersjonowania

| Strategia | Przykład |
|---|---|
| URI path | `GET /v2/orders/42` |
| Header | `Accept: application/vnd.api.v2+json` |
| Schema evolution | dodaj pola, nigdy nie usuwaj/zmień nazwy |

## Preferuj zmiany addytywne (bez przerywania)

```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 jest do tego przyjazny

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

Numery pól, a nie nazwy, definiują format przewodu, dlatego dodawanie pól jest wstecznie kompatybilne.

## Dlaczego to ważne

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

## Pułapka

Nigdy nie usuwaj wersji, jeśli rzeczywisty ruch nadal jej używa. Śledzić użycie przed wycofaniem.

## Dlaczego to ważne

Niezależne wdrażalność działa tylko wtedy, gdy producent może dostarczyć zmianę bez koordynowania wydania każdego konsumenta.

Projektowanie pod kątem zmian addytywnych i wspieranie starych wersji podczas migracji to to, co zachowuje tę niezależność zamiast zmuszać do kruchych uaktualnień typu big-bang.

URI path	`GET /v2/orders/42`
Header	`Accept: application/vnd.api.v2+json`
Schema evolution	dodaj pola, nigdy nie usuwaj/zmień nazwy