Versionhantering

Ett API kommer att förändras över tid och kommer därför att behöva versionshanteras.

Bakåtkompabilitet

Ett API BÖR (VER.01) så långt som möjligt ha en lös koppling mellan producent och konsument. Därför är bakåtkompabilitet en viktig aspekt för ett API. Med ett bakåtkompatibelt API kan förändringar i ett API genomföras utan att påverka konsumenten av API:et.

Följande är exempel på typer av ändringar anses bakåtkompatibla:

  • Tillägg av ett nytt valfritt fält till en representation
  • Tillägg av en ny länk till _links listan för en representation
  • Tillägg för en ny resurs för ett API
  • Tillägg av ny valfri sökparameter
  • Ytterligare support för mediatyper
  • Borttag av icke obligatoriska fält från representationer

Följande är exempel på typer av ändringar anses vara icke bakåtkompatibla:

  • Borttag av obligatoriska fält från representationer
  • Ändring av datatyp på fält
  • Borttag av resurser eller operationer
  • Borttag av support för mediatyp

Även beteendeändringar hos ett API kan vara icke bakåtkompatibla även om gränssnittet är intakt. Se även upp med exempelvis Även beteendeändringar hos ett API kan vara icke bakåtkompatibla även om gränssnittet är intakt. Se även upp med exempelvis scheman och dess validering, där även bakåtkompatibla ändringar som tillägg av fält i en XML-struktur kan ge valideringsfel om ANY-elementet saknas i schemat.

Att införa icke bakåtkompatibla förändringar, dvs införa en ny MAJOR-version, är komplext både för konsumenter och producenter. Varje ny MAJOR version kräver att äldre versioner stöds tills alla konsumenter bytt till senaste version. Ju fler versioner som stöds, desto större belastning på API:ets förvaltning och support. 

Som producent av ett API BÖR (VER.02) man undvika att införa icke bakåtkompatibla ändringar i sitt API och ibland är det oundvikligt. Som konsument BÖR (VER.03) man alltid vara tolerant, förvänta sig och hantera oväntade svar i ett meddelande. Detta skapar robusthet.

Versionsnumrering

Samtliga API:er SKALL (VER.04) använda semantisk versionshantering:

{MAJOR}.{MINOR}.{PATCH}

Enligt semantisk versionshantering, hanteras kommande versioner enligt följande:

MAJOR version ökas med 1 när du gör ändringar som påverkar bakåtkompatibiliteten för API:et.

MINOR version ökas med 1 när du lägger till ny funktionalitet men 100 % bakåtkompatibilitet bibehålls.

PATCH version ökas med 1 när du fixar buggar förutsatt att 100 % bakåtkompatibilitet bibehålls.

Versionsnumrering i URL:er

Alla API:er BÖR (VER.05) inkludera MAJOR versionen i den URL som används för ett specifikt API. 

Exempelvis

https://gw.api.bolagsverket.se/foretagsinformation/v2/

MINOR och PATCH versionerna används inte i URL:n då bakåtkompabilitet råder.

Information om ett API och dess version

Att informera konsumenter om kommande ändringar är viktigt och det kan ske på olika sätt. Exempelvis kan man ta kontakt med samtliga konsumenter och informera om förändringar. Ibland är detta inte möjligt och då kan man informera via webbsidan där dokumentationen finns eller om man har nyhetsbrev kan detta vara en kanal. Det går även att tekniskt informera förändringar via en specifik resurs eller som en del av svarsmeddelandet på ett API-anrop, se nedan.

API nycklar eller liknande kan användas för att identifiera användare och därmed veta vilka som använder gamla versioner och stödja dem i sin uppgradering, för att då kunna avveckla de gamla versionerna. 

Resursen api-info

Information om ett API SKALL (VER.06) tillgängliggöras via resursen api-info under roten till API:et. Genom att utföra GET på resursen api-info SKALL (VER.07) följande information returneras (exemplet nedan med camelCase).

  • apiName: Namn på API
  • apiVersion: API-version med MAJOR, MINOR och PATCH version
  • apiReleased: Datum som denna API-version publicerades
  • apiDocumentation: En länk till aktuell API dokumentation. Om API:et består av flera delar (t.ex. flera webbsidor) bör en samlingsplats skapas för alla delar skapas där alla delar är åtkomliga via länkar eller liknande.
  • apiStatus: Visar API:ets tillstånd eller status enligt livscykelhantering längre ned på denna sida. T.ex. beta, active eller deprecated.

Ovan information ska anges, men ytterligare attribut och värden kan läggas till om önskas.

Exempel:

GET https://gw.api.bolagsverket.se/foretagsinformation/v1/api-info
//HTTP 200 OK
{
"apiName": "foretagsinformation",
"apiVersion": "2.0.1"
"apiReleased": "2022-11-03"
"apiDocumentation": "https://gw.api.bolagsverket.se/foretagsinformation/v2/dokumentation"
"apiStatus": "active"
}

API utfasning

Utfasning (eng. deprecation) av ett API sker när ett nyare API finns tillgängligt. API ägare BÖR (VER.08) informera konsumenten i svaret på ett anrop, när en gammal version används. Denna information förser konsumenten med en påminnelse att API:et kommer att ersättas och att det troligen redan finns en nyare version redo att migrera till.

För att ange information om utfasning i svaret på ett anrop används bland annat förslaget till standard The Deprecation HTTP Header Field (Dalal Deprecation Header) samt standarderna RFC 8594 (Sunset HTTP Header Field) samt RFC 8288 (Web Linking). 

Fältet Deprecation följt av ett datum i svaret indikerar för konsumenten att en nyare version av API:t finns. Fältet Sunset följt av ett datum i svaret indikerar att denna version av API:t slutar att fungera vid det aktuella datumet. Datumet anges enligt standarden RFC 3339. Till dessa två fält kan man också lägga till länkar till den nyaste versionen eller ett alternativt API som man kan använda. Något av följande relationsvärden BÖR (VER.09) användas

  • successor-version: Pekar på den resurs som efterträdande den resurs som anropades (RFC 5829)
  • latest-version: Pekar på den senaste versionen av resursen (RFC 5829)
  • alternate: Pekar på en alternativ resurs (HTML 4.01 Specification)

Följande exempel visar hur ett svar på ett API som är under utfasning kan se ut.

GET `https://gw.api.bolagsverket.se/foretagsinformation/v2/organisationer/5568108988`

// 200 OK
Deprecation: 01 Jan 2022 00:00:00 UTC+1
Link: https://gw.api.bolagsverket.se/foretagsinformation/v2/; rel="latest-version"
Sunset: 30 Jun 2023 23:59:59 UTC+1

Content-Type: application/json
{
  "namn" : "Volvo Cars AB",
  "organisationsnummer" : "5568108988",
  "bolagsform" : "Aktiebolag",
  "registreringsar" : "2010"
 }

Livscykelhantering

Ett API genomgår, precis som vilken produkt som helst, en livscykel, från utveckling tills dess att den tas ur bruk. Med ett tydligt och gemensamt regelverk för vilka tillstånd ett API kan befinna sig i blir det enklare för konsumenter av ett API att förstå vad som kan förväntas av API:et gällande exempelvis dokumentation och support.

Tillstånd för ett API

Följande tillstånd eller status BÖR (VER.10) användas för att beskriva vart i livscykeln ett API befinner sig i.

  • alpha
  • beta
  • active
  • deprecated
  • retired
  • decommisioned

En livscykel kan indelas i tre faser; utvecklingsfasen, aktiv fas samt avvecklingsfas.

Utvecklingsfas

Under utvecklingsfasen är det lämpligt att skilja på de två tillstånden alpha och beta. alpha används främst internt inom organisationen, medan beta kan förekomma i t.ex. integrationstester med andra organisationer. 

‎alpha

Ett API i status alpha genomgår snabb iteration med en känd uppsättning användare, där användarna måste vara toleranta mot förändring. Antalet användare är relativt få i antal, så att det är möjligt att kommunicera med dem alla individuellt.

Att införa icke bakåtkompatibla ändringar är både tillåtet och förväntat för API:er i status alpha, och användarna kan inte förvänta sig några krav på stabilitet. 

beta

Ett API i status beta anses vara fullständigt och redo att förklaras active i närtid. API:er i status beta kan exponeras för en okänd och potentiellt stor uppsättning användare och anses tillgänglig för allmänheten.

Eftersom användare av beta API:er tenderar att ha en lägre tolerans för förändring bör dessa vara så stabila som möjligt men tillåtas ändras med tiden som omfattar även icke bakåtkompatibla ändringar.

Aktiv fas

I denna fas har API:et lämnat utvecklingsfasen och är allmänt tillgängligt.

active 

Ett API i status active är den senaste versionen och är fullt supporterad. Det är den rekommenderade versionen att använda. Ibland kallas denna status också för general availability, GA. 

Avvecklingsfas

API:er är inte avsedda att finnas för evigt, utan producenten har ett ansvar att tydligt förmedla när API:et kommer att dras tillbaka. Vissa API:er syftar bara till att stödja ett begränsat användningsfall under en kortare tid, för att sedan förvinna och kanske ersättas med ett nyare bättre anpassat API.

En End-of-Life (EOL) policy definierar en process som API:er går igenom i dess livscykel, från active till decommissioned.

Policyn avser att säkra en tydlig och konsistent tidsplan som API konsumenter kan ta del av för att planera sin migration från de äldre API:erna till de nya. Konsumenten kan därmed planera hur de ska hantera sin tekniska skuld som förflyttningen ger. 
 

deprecated

En API version i status deprecated har efterträtts av en nyare version. Den supporteras ofta i flera månader efter den hamnar i status deprecated.

retired 

En API version i status retired supporteras inte längre. Applikationer som använder en API som är retired ska migrera till en API version i status active så fort som möjligt.

decommissioned

En API version i status decommissioned är inte längre tillgänglig i produktion. Denna fas infaller efter status retired. Denna status kallas ibland för sunset, se vidare avsnitt API utfasning ovan. 

Versionshanteringsregler för ett API:s livscykel

Versioner som befinner sig i status alpha eller beta SKALL (VER.11) börja med en MAJOR version med siffran ”0”. I övrigt gäller samma regler som för versionshantering i den aktiva fasen.

API:ets första publika version i status active SKALL (VER.12) alltid börja med en MAJOR version med siffran ”1”.

Eftersom MINOR versioner är bakåtkompatibla med föregående MINOR versioner inom samma MAJOR version SKALL (VER.13) MINOR versioner anses retired direkt när en ny MINOR version av samma MAJOR version blir active. Förändringar av denna sort bör inte ha någon påverkan på befintliga konsumenter, så API:et behöver inte gå igenom status deprecated och därmed en migrering för kund.

När en ny MAJOR version publiceras så SKALL (VER.14) de äldre versionerna fasas ut. En MAJOR version SKALL INTE (VER.15) sättas till deprecated förrän en ersättare är active och det finns en tydlig migrationsväg för all funktionalitet som upprätthålls framåt. Detta BÖR (VER.16) inkludera dokumentation och migrationsverktyg/exempelkod som beskriver vad konsumenterna behöver göra för en ren migration. Enda undantaget är i fall API:et ska fasas ut helt och hållet.

Om ett API ska sättas till deprecated och samtidigt har externa konsumenter BÖR (VER.17) tid för utfasning och begränsningar övervägas för att minimera kundpåverkan. API i statusen deprecated SKALL (VER.18) vara i status deprecated under en tillräckligt lång tid för att ge konsumenterna möjlighet att kunna migrera.

Om ett API i status active eller deprecated inte har några användare så BÖR (VER.19) det direkt sättas i status retired.