Jakie są główne strategie wersjonowania API i jak wycofać wersję?

Question

IT Interview Practice · Accepted Answer

Wersjonowanie pozwala rozwijać API ze **zmianami łamiącymi (breaking changes)** bez psucia istniejących klientów. Istnieją trzy główne strategie plus proces wycofywania (deprecation).

## Trzy strategie

**1. Wersjonowanie w URI** — wersja jest w ścieżce.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Najprostsze i najbardziej widoczne; łatwe do routingu, cache'owania i testowania w przeglądarce. Wada: technicznie łamie zasadę „URI identyfikuje zasób" (ten sam użytkownik ma teraz dwa URL-e). To zdecydowanie najczęstszy wybór (GitHub, Stripe historycznie).

**2. Wersjonowanie w niestandardowym nagłówku** — wersja podróżuje w nagłówku.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Utrzymuje URL-e w czystości, ale jest niewidoczne w przeglądarce i trudniejsze do cache'owania.

**3. Wersjonowanie przez media-type (negocjacja treści)** — wersja w `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Najbardziej „RESTful" (URL zasobu jest stabilny; wersjonowana jest tylko jego reprezentacja), ale najmniej przystępne dla konsumentów.

## Co liczy się jako łamiące

```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*
```
Tylko zmiany łamiące wymagają nowej wersji; zmiany niełamiące dodawaj do bieżącej.

## Proces wycofywania

1. **Ogłoś** z datami w dokumentacji i changelogu.
2. **Sygnalizuj w czasie działania** za pomocą nagłówków, by klienci zauważyli to programowo:
```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. **Monitoruj** użycie starej wersji i skontaktuj się z pozostałymi wywołującymi.
4. **Wyłącz (sunset)** dopiero, gdy użycie spadnie blisko zera.

## Dlaczego to ważne

Rozmówcy pytają o to, by zobaczyć, czy potrafisz rozwijać API na produkcji bez psucia klientów, którzy od niego zależą — to realny problem operacyjny, nie teoretyczny. Najmocniejsze odpowiedzi robią dwa rozróżnienia: po pierwsze, że **większość zmian jest niełamiąca** i wcale nie powinna wyzwalać podbicia wersji (zmiany addytywne idą do bieżącej wersji), rezerwując wersjonowanie dla naprawdę łamiących zmian; po drugie, że *strategia* ma mniejsze znaczenie niż *proces* — jasny harmonogram wycofywania z nagłówkami `Deprecation`/`Sunset` i monitorowaniem użycia to jest to, co faktycznie chroni konsumentów. Wersjonowanie w URI wygrywa w praktyce dzięki widoczności i wsparciu narzędzi, ale znajomość kompromisów (nagłówek i media-type utrzymują stabilne URL-e i są bardziej RESTful, kosztem odkrywalności) pokazuje, że rozumiesz przestrzeń projektową, a nie tylko bezmyślnie kopiujesz `/v1/`.

Trzy strategie

Co liczy się jako łamiące

Proces wycofywania

Dlaczego to ważne

Powiązane pytania