Mitkä ovat tärkeimmät API-versiointistrategiat, ja miten deprekoit version?

Question

IT Interview Practice · Accepted Answer

Versiointi antaa sinun kehittää API:a **breaking changein** avulla rikkomatta olemassa olevia clientejä. On kolme valtavirtastrategiaa plus deprekaatioprosessi.

## Kolme strategiaa

**1. URI-versiointi** — versio on polussa.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Yksinkertaisin ja näkyvin; helppo reitittää, cachettaa ja testata selaimessa. Haittapuoli: se teknisesti rikkoo periaatetta "URI tunnistaa resurssin" (samalla käyttäjällä on nyt kaksi URL:ää). Tämä on ylivoimaisesti yleisin valinta (GitHub, Stripe historiallisesti).

**2. Custom header -versiointi** — versio kulkee headerissa.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Pitää URL:t siisteinä mutta on näkymätön selaimessa ja vaikeampi cachettaa.

**3. Media-type (content negotiation) -versiointi** — versio `Accept`issa.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
"RESTful"-eimmin (resurssin URL on vakaa; vain sen representaatio versioidaan), mutta vähiten lähestyttävä kuluttajille.

## Mikä lasketaan breakingiksi

```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*
```
Vain breaking changet tarvitsevat uuden version; lisää non-breaking-muutokset nykyiseen.

## Deprekaatioprosessi

1. **Ilmoita** päivämäärineen dokumentaatiossa ja changelogissa.
2. **Signaloi ajonaikaisesti** headereilla, jotta clientit huomaavat ohjelmallisesti:
```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. **Monitoroi** vanhan version käyttöä ja ota yhteyttä jäljellä oleviin kutsujiin.
4. **Sulje (sunset)** vasta kun käyttö laskee lähelle nollaa.

## Miksi se on tärkeää

Haastattelijat kysyvät tätä nähdäkseen, osaatko kasvattaa API:a tuotannossa rikkomatta siitä riippuvia clientejä — todellinen operatiivinen huoli, ei teoreettinen. Vahvimmat vastaukset tekevät kaksi erottelua: ensinnäkin, että **useimmat muutokset ovat non-breaking** eivätkä saisi laukaista versiobumppia lainkaan (additiiviset muutokset menevät nykyiseen versioon), varaten versioinnin aidosti rikkoville muutoksille; ja toiseksi, että *strategia* on vähemmän tärkeä kuin *prosessi* — selkeä deprekaatioaikataulu `Deprecation`/`Sunset`-headereineen ja käytön monitorointi on se, mikä oikeasti suojaa kuluttajia. URI-versiointi voittaa käytännössä näkyvyytensä ja työkalutukensa vuoksi, mutta kompromissien tunteminen (header ja media-type pitävät URL:t vakaina ja ovat RESTful-eimpiä, löydettävyyden kustannuksella) osoittaa, että ymmärrät suunnitteluavaruuden etkä vain kopioi `/v1/`.

Kolme strategiaa

Mikä lasketaan breakingiksi

Deprekaatioprosessi

Miksi se on tärkeää

Aiheeseen liittyvät kysymykset