Mikä on API-versiointi
API-versioiden hallinta
API-versiointi
API-versiointi on käytäntö API-muutosten hallintaan säilyttäen taaksepäin yhteensopivuus olemassa oleville asiakkaille.
Versiointistrategiat
| Strategia | Esimerkki | Kuvaus | |-----------|-----------|--------| | URL-polku | /api/v1/users | Versio URL-polussa | | Query-parametri | /api/users?version=1 | Versio parametrissa | | Header | X-API-Version: 1 | Versio headerissa | | Content Type | Accept: application/vnd.api.v1+json | Mediatyyppiversio |
Semanttinen versiointi
- Major (v1→v2) — rikkovat muutokset
- Minor (v1.1→v1.2) — uudet ominaisuudet, taaksepäin yhteensopiva
- Patch (v1.1.0→v1.1.1) — vikakorjaukset
Parhaat käytännöt
- Dokumentoi kaikki muutokset (changelog)
- Tue vähintään 2 versiota
- Ilmoita deprecation etukäteen
- Käytä sunset-headereita
- Tarjoa migraatiotyökalut
Milloin uusi versio tarvitaan
- Kenttien tai endpointtien poisto
- Vastausmuodon muutos
- Parametrien semantiikan muutos
- Autentikoinnin muutos