APIversiooni

APIversioon tähistab üht konkreetset seisundit API-st, mis määrab liideste nimekirja, andmestruktuurid ja käitumise. Versioonimine võimaldab teenusel kasvada ja uuendada ning samal ajal tagada klientidele stabiilse ja prognoositava kasutuskeskkonna. Tähtis on eristada tagantjärele ühilduvust (backwards compatibility) ning katkestavaid muudatusi (breaking changes), mis võivad nõuda kliendi koodis muudatusi.

Kõige levinumad versioonimisviisid on: teekond- või URL-põhine versioonimine, kus erinevad versioonid on eristatud aadressis (näiteks /api/v1/..., /api/v2/...), päringumuutuja kaudu versioneerimine (näiteks /api/ressursid?versioon=1) ning päisipõhine või sisu-täpsustava meedia-tüübi versionimine (nt Accept: application/vnd.company.v1+json). Kaasaegsetes süsteemides kasutatakse sageli kombinatsioone ning valitakse lähenemine, mis sobib kõige paremini arhitektuuri, kliendibaasi ja turvanõuetega.

Semantiline versioonimine (SemVer) on laialt levin, kus versioon on kujul MAJOR.MINOR.PATCH ja reeglid määravad, millal on tegu katkendliku või ühilduva uuendusega. API-de puhul võib olla eraldi versioon kontraktiline, mis tähistab, millist päringut ja vastust oodatakse, sõltumata tegelikust tootest.

Elutsükkel ja haldus: vanemad versioonid säilitatakse teatud aja, teavitatakse deprecatsioonist ning pakutakse migratsioonijuhiseid ja tööriistu. Üldine praktika on piirata raskesti hooldatavaid versioone ning teha selge deprecation-poliitika, dokumentatsioon ja muutuste teavitus, et arendajad saaksid võimalikult sujuvalt uuendada. Navigeerimine versioonide vahel toimub tavaliselt API-gatewaysi, kontraktitestide ja hoolduskavade abil.