Ett naturligt steg inom API-Management bör innefatta versionshantering. Ämnet går ofta ihop med dokumentation och namnstandard men i stora drag brukar man separera versionhantering i integrationsbrytande samt icke-integrationsbrytande ändringar.
Integrationsbrytande versionshantering
Vanligen en major up-version (v1 –> v2)
Exempel på ”integrationsbrott”:
- Ett byte i anropet / svarets typ (integer –> float)
- Avveckling av delar av API’et
- Ett byte i format på svarsdatat
Icke integrationsbrytande versionshantering
Vanligen en minor up-version (v1.0 –> v.1.0.1)
Exempel på ”icke-brott”:
- Ändring i endpoint
- Ändring i svarsparametrar
Metoder för versionsändringar
URI versionshantering
URL versionshantering är kanske den ”vanligaste” typen där man på ett enkelt sätt via endpoint kan inkludera version.
Tex:
https://api.topapi.se/api/v1/airplanes/
https://api.topapi.se/api/v2/airplanes/
Fördelen med detta är att man på ett enkelt sätt kan både se och managera version, men man får tänka till vid uppgradering för att inte begå brott!
Alternativa versionshanteringar via relativa url’er samt header (Accept-version) är några alternativ som kanske främst tillämpas där värdet av att hålla den äkta url’en intakt till varje pris! samt
Separation på API version och resurshantering? Har man någonsin fler versioner levande i produktion samtidigt? Fördelar/nackdelar med minor-version uppgraderingar?