APIversjonering

APIversjonering er praksisen å introdusere og administrere versjoner av et API for å håndtere endringer i grensesnittet over tid. Hensikten er å bevare stabilitet for eksisterende klienter samtidig som utviklere kan levere nye funksjoner og feilrettinger. En tydelig versjonering gjør det mulig for klienter å velge når de vil migrere til en nyere utgave og gir operatører kontroll over livssyklusen til hver versjon.

Vanlige tilnærminger inkluderer å slå versjonen inn i URL-en (path versioning), for eksempel /api/v1/ressurser; å sende versjonen i en HTTP-header eller i en query-parameter; og i noen tilfeller å bruke innholdssamsvar (Accept-header) eller mediatype for å velge versjon. Hvilken strategi som velges påvirker enkelhet, caching og mellomvarelogikk i infrastruktur som API-gatewayer.

Når det gjelder semantikk, bruker mange API-er SemVer eller lignende prinsipper: MAJOR-VER 1.0.0 indikerer breaking changes, MINOR gir ny funksjonalitet som er bakoverkompatibel, og PATCH kun feilrettinger. En klar livssykluspolitikk er viktig, inkludert deprecieringsplaner, varsler til kunder, og en sunset-tidshorisont som gjør migrasjon håndterbar.

Beste praksiser inkluderer å begrense antall aktive hovedversjoner samtidig, dokumentere endringer grundig, tilby migrasjonsveiledninger og omfattende regresjonstester. Noen arkitekturer benytter også API-gateways eller kontraktbasert styring for å styre versjonsdremmen og migrasjon.

GraphQL skiller seg ofte ved at det ikke følger tradisjonell versjonering i samme grad, siden schemaene kan evolvere med deprecating og ny felt i stedet for å utstede separate versjoner.