Quali sono le principali strategie di versioning delle API, e come deprechi una versione?

Question

IT Interview Practice · Accepted Answer

Il versioning ti permette di evolvere un'API con **breaking change** senza rompere i client esistenti. Ci sono tre strategie principali, più un processo di deprecazione.

## Le tre strategie

**1. URI versioning** — la versione è nel path.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
La più semplice e visibile; facile da instradare, mettere in cache e testare in un browser. Svantaggio: viola tecnicamente il principio "l'URI identifica una risorsa" (lo stesso utente ora ha due URL). È di gran lunga la scelta più comune (GitHub, Stripe storicamente).

**2. Custom header versioning** — la versione viaggia in un header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Mantiene puliti gli URL ma è invisibile in un browser e più difficile da mettere in cache.

**3. Media-type (content negotiation) versioning** — versione in `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Il più "RESTful" (l'URL della risorsa è stabile; solo la sua rappresentazione è versionata), ma il meno accessibile per i consumatori.

## Cosa conta come 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*
```
Solo le breaking change richiedono una nuova versione; aggiungi le non-breaking a quella attuale.

## Processo di deprecazione

1. **Annuncia** con date nella documentazione e nel changelog.
2. **Segnala a runtime** con header così che i client se ne accorgano programmaticamente:
```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. **Monitora** l'uso della vecchia versione e contatta i chiamanti rimasti.
4. **Sunset** solo dopo che l'uso cala vicino a zero.

## Perché è importante

Gli intervistatori chiedono questo per vedere se sai far crescere un'API in produzione senza rompere i client che ne dipendono — una preoccupazione operativa reale, non teorica. Le risposte più forti fanno due distinzioni: primo, che **la maggior parte delle modifiche è non-breaking** e non dovrebbe affatto innescare un bump di versione (le modifiche additive vanno nella versione attuale), riservando il versioning alle modifiche genuinamente breaking; e secondo, che la *strategia* conta meno del *processo* — una timeline di deprecazione chiara con header `Deprecation`/`Sunset` e il monitoraggio dell'uso è ciò che davvero protegge i consumatori. L'URI versioning vince nella pratica per la sua visibilità e il supporto del tooling, ma conoscere i compromessi (header e media-type mantengono gli URL stabili e sono più RESTful, al costo della scopribilità) mostra che capisci lo spazio di design anziché limitarti a imitare per abitudine `/v1/`.

Le tre strategie

Cosa conta come breaking

Processo di deprecazione

Perché è importante

Domande correlate