Jaké jsou hlavní strategie versioningu API a jak deprekovat verzi?

Question

IT Interview Practice · Accepted Answer

Versioning umožňuje rozvíjet API s **breaking changes** bez rozbití stávajících klientů. Existují tři hlavní strategie plus proces deprekace.

## Tři strategie

**1. URI versioning** — verze je v cestě.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Nejjednodušší a nejviditelnější; snadné routovat, cachovat a testovat v prohlížeči. Nevýhoda: technicky porušuje „URI identifikuje zdroj“ (tentýž uživatel má teď dvě URL). Je to zdaleka nejběžnější volba (GitHub, Stripe historicky).

**2. Custom header versioning** — verze cestuje v hlavičce.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Udržuje URL čisté, ale je neviditelné v prohlížeči a hůře se cachuje.

**3. Media-type (content negotiation) versioning** — verze v `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Nejvíce „RESTful“ (URL zdroje je stabilní; verzuje se jen jeho reprezentace), ale nejméně přístupné pro konzumenty.

## Co se počítá jako breaking

```text
BREAKING      → odebrat/přejmenovat pole, změnit typ, změnit auth, zpřísnit validaci
NON-BREAKING  → přidat nové volitelné pole, přidat nový endpoint, přidat hodnotu enumu*
```
Novou verzi potřebují jen breaking changes; non-breaking změny přidávejte do stávající verze.

## Proces deprekace

1. **Oznamte** s daty v dokumentaci a changelogu.
2. **Signalizujte za běhu** pomocí hlaviček, aby si toho klienti všimli programově:
```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. **Monitorujte** používání staré verze a kontaktujte zbývající volající.
4. **Vypněte (sunset)** teprve poté, co používání klesne téměř na nulu.

## Proč je to důležité

Tazatelé to pokládají, aby zjistili, zda dokážete rozvíjet API v produkci bez rozbití klientů, kteří na něm závisí — reálná provozní starost, ne teoretická. Nejsilnější odpovědi činí dvě rozlišení: zaprvé, že **většina změn je non-breaking** a neměla by vůbec vyvolávat zvýšení verze (aditivní změny jdou do stávající verze) a versioning se vyhrazuje pro skutečně breaking změny; a zadruhé, že na *strategii* záleží méně než na *procesu* — jasný harmonogram deprekace s hlavičkami `Deprecation`/`Sunset` a monitoringem používání je to, co konzumenty skutečně chrání. URI versioning v praxi vítězí pro svou viditelnost a podporu nástrojů, ale znalost kompromisů (hlavička a media-type udržují URL stabilní a jsou více RESTful, za cenu objevitelnosti) ukazuje, že rozumíte návrhovému prostoru, a ne že jen slepě kopírujete `/v1/`.

Tři strategie

Co se počítá jako breaking

Proces deprekace

Proč je to důležité

Související otázky