Care sunt principalele strategii de versioning API și cum deprechezi o versiune?

Question

IT Interview Practice · Accepted Answer

Versioning-ul îți permite să evoluezi un API cu **breaking changes** fără să strici clienții existenți. Există trei strategii mainstream, plus un proces de deprecare.

## Cele trei strategii

**1. URI versioning** — versiunea este în path.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Cel mai simplu și mai vizibil; ușor de rutat, cache-uit și testat într-un browser. Dezavantaj: încalcă tehnic „URI-ul identifică o resursă" (același utilizator are acum două URL-uri). Este de departe cea mai comună alegere (GitHub, Stripe istoric).

**2. Custom header versioning** — versiunea călătorește într-un header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Menține URL-urile curate, dar este invizibilă într-un browser și mai greu de cache-uit.

**3. Media-type (content negotiation) versioning** — versiunea în `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Cea mai „RESTful" (URL-ul resursei este stabil; doar reprezentarea ei este versionată), dar cea mai puțin accesibilă pentru consumatori.

## Ce contează ca breaking

```text
BREAKING      → elimină/redenumește un câmp, schimbă un tip, schimbă auth, strânge validarea
NON-BREAKING  → adaugă un câmp opțional nou, adaugă un endpoint nou, adaugă o valoare enum*
```
Doar breaking changes au nevoie de o versiune nouă; adaugă modificările non-breaking la cea curentă.

## Procesul de deprecare

1. **Anunță** cu date în documentație și changelog.
2. **Semnalează la runtime** cu headere ca să observe clienții programatic:
```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. **Monitorizează** utilizarea versiunii vechi și contactează apelanții rămași.
4. **Sunset** doar după ce utilizarea scade aproape de zero.

## De ce contează

Intervievatorii întreabă asta pentru a vedea dacă poți dezvolta un API în producție fără să strici clienții care depind de el — o preocupare operațională reală, nu una teoretică. Cele mai bune răspunsuri fac două distincții: în primul rând, că **majoritatea modificărilor sunt non-breaking** și nu ar trebui deloc să declanșeze un bump de versiune (modificările aditive intră în versiunea curentă), rezervând versioning-ul pentru modificări cu adevărat breaking; și în al doilea rând, că *strategia* contează mai puțin decât *procesul* — un calendar clar de deprecare cu headere `Deprecation`/`Sunset` și monitorizarea utilizării este ceea ce protejează de fapt consumatorii. URI versioning câștigă în practică datorită vizibilității și suportului de tooling, dar cunoașterea compromisurilor (header și media-type mențin URL-urile stabile și sunt mai RESTful, cu prețul descoperibilității) arată că înțelegi spațiul de design în loc să copiezi orbește `/v1/`.

Cele trei strategii

Ce contează ca breaking

Procesul de deprecare

De ce contează

Întrebări conexe