Wat zijn de belangrijkste API-versioningstrategieën, en hoe deprecate je een versie?

Question

IT Interview Practice · Accepted Answer

Versioning laat je een API laten evolueren met **breaking changes** zonder bestaande clients te breken. Er zijn drie mainstream-strategieën, plus een deprecation-proces.

## De drie strategieën

**1. URI-versioning** — de versie zit in het pad.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Eenvoudigst en meest zichtbaar; makkelijk te routeren, cachen en testen in een browser. Nadeel: het schendt technisch "de URI identificeert een resource" (dezelfde user heeft nu twee URL's). Dit is verreweg de gangbaarste keuze (GitHub, Stripe historisch).

**2. Custom-header-versioning** — de versie reist in een header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Houdt URL's schoon maar is onzichtbaar in een browser en lastiger te cachen.

**3. Media-type-versioning (content negotiation)** — versie in `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Het meest "RESTful" (de resource-URL is stabiel; alleen de representatie krijgt een versie), maar het minst toegankelijk voor consumers.

## Wat telt als breaking

```text
BREAKING      → remove/rename a field, change a type, change auth, tighten validation
NON-BREAKING  → add a new optional field, add a new endpoint, add an enum value*
```
Alleen breaking changes hebben een nieuwe versie nodig; voeg non-breaking changes toe aan de huidige.

## Deprecation-proces

1. **Kondig aan** met datums in docs en changelog.
2. **Signaleer tijdens runtime** met headers zodat clients het programmatisch opmerken:
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. **Monitor** het gebruik van de oude versie en benader de resterende callers.
4. **Sunset** pas nadat het gebruik bijna nul is.

## Waarom het belangrijk is

Interviewers vragen dit om te zien of je een API in productie kunt laten groeien zonder de clients die ervan afhankelijk zijn te breken — een echte operationele zorg, geen theoretische. De sterkste antwoorden maken twee onderscheidingen: ten eerste dat **de meeste changes non-breaking zijn** en helemaal geen versiebump zouden moeten triggeren (additieve changes gaan naar de huidige versie), waardoor versioning gereserveerd blijft voor echt breaking changes; en ten tweede dat de *strategie* minder uitmaakt dan het *proces* — een heldere deprecation-tijdlijn met `Deprecation`/`Sunset`-headers en gebruiksmonitoring is wat consumers daadwerkelijk beschermt. URI-versioning wint in de praktijk vanwege zijn zichtbaarheid en tooling-ondersteuning, maar de afwegingen kennen (header en media-type houden URL's stabiel en zijn meer RESTful, ten koste van ontdekbaarheid) laat zien dat je de ontwerpruimte begrijpt in plaats van alleen `/v1/` na te apen.

De drie strategieën

Wat telt als breaking

Deprecation-proces

Waarom het belangrijk is

Gerelateerde vragen