Hoe versie je API's en behoud je achterwaartse compatibiliteit in services?

Question

Accepted Answer

Omdat services onafhankelijk worden geïmplementeerd, kunt u nooit aannemen dat aanroepers synchroon upgraden. **API-versiebeheer** plus **achterwaartse compatibiliteit** stelt producers in staat om te evolueren zonder bestaande consumenten te breken.

## Versiestrategieën

| Strategie | Voorbeeld |
|---|---|
| URI path | `GET /v2/orders/42` |
| Header | `Accept: application/vnd.api.v2+json` |
| Schema evolution | voeg velden toe, verwijder/hernoem nooit |

## Geef de voorkeur aan additieve (niet-brekende) wijzigingen

```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 is hieraan bevorderlijk

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

Veldnummers, geen namen, bepalen het wire-formaat, dus het toevoegen van velden is achterwaarts compatibel.

## Lifecycle

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

## Nadeel

Verwijder een versie nooit terwijl er nog echt verkeer doorheen gaat. Controleer het gebruik voordat u pensioen gaat.

## Waarom het belangrijk is

Onafhankelijke implementeerbaarheid werkt alleen als een producer een wijziging kan uitrollen zonder de release van elke consumer te coördineren.

Ontwerpen voor additieve verandering en ondersteuning van oude versies tijdens migratie is wat die onafhankelijkheid bewaart in plaats van fragiele big-bang upgrades af te dwingen.

URI path	`GET /v2/orders/42`
Header	`Accept: application/vnd.api.v2+json`
Schema evolution	voeg velden toe, verwijder/hernoem nooit