Kokios yra pagrindinės API versijavimo strategijos ir kaip deprekuoti versiją?

Question

IT Interview Practice · Accepted Answer

Versijavimas leidžia plėtoti API su **breaking changes** nesugadinant esamų klientų. Yra trys pagrindinės strategijos ir dar deprekacijos procesas.

## Trys strategijos

**1. URI versijavimas** — versija yra kelyje.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Paprasčiausia ir matomiausia; lengva maršrutizuoti, cache’inti ir testuoti naršyklėje. Trūkumas: techniškai pažeidžia „URI identifikuoja išteklių“ (tas pats user dabar turi du URL). Tai toli gražu dažniausias pasirinkimas (GitHub, Stripe istoriškai).

**2. Custom header versijavimas** — versija keliauja header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Laiko URL švarius, bet nematoma naršyklėje ir sunkiau cache’inama.

**3. Media-type (content negotiation) versijavimas** — versija `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
„RESTful“-iausias (ištekliaus URL stabilus; versionuojama tik jo reprezentacija), bet mažiausiai prieinamas vartotojams.

## Kas laikoma 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*
```
Tik breaking changes reikia naujos versijos; non-breaking pakeitimus pridėk į dabartinę.

## Deprekacijos procesas

1. **Paskelbk** su datomis dokumentacijoje ir changelog.
2. **Signalizuok vykdymo metu** su header, kad klientai pastebėtų programiškai:
```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. **Stebėk** senos versijos naudojimą ir susisiek su likusiais iškviečiančiais.
4. **Sunset** tik kai naudojimas nukrenta beveik iki nulio.

## Kodėl tai svarbu

Interviuotojai to klausia, kad pamatytų, ar galite auginti API production nesugadindami nuo jo priklausančių klientų — realus operacinis rūpestis, ne teorinis. Stipriausi atsakymai daro du atskyrimus: pirma, kad **dauguma pakeitimų yra non-breaking** ir apskritai neturėtų sukelti versijos šuolio (papildantys pakeitimai eina į dabartinę versiją), rezervuojant versijavimą tikram breaking pakeitimui; antra, kad *strategija* svarbi mažiau nei *procesas* — aiškus deprekacijos grafikas su `Deprecation`/`Sunset` header ir naudojimo stebėjimu yra tai, kas iš tikrųjų apsaugo vartotojus. URI versijavimas praktikoje laimi dėl matomumo ir įrankių palaikymo, bet kompromisų žinojimas (header ir media-type laiko URL stabilius ir yra labiau RESTful, atsisakant atrandamumo) rodo, kad suprantate projektavimo erdvę, o ne vien kopijuojate `/v1/`.

Trys strategijos

Kas laikoma breaking

Deprekacijos procesas

Kodėl tai svarbu

Susiję klausimai