Dokumentation

Väldokumenterade API:er är centrala. Med hjälp av gemensamt strukturerad dokumentation skapas förutsättningar för interoperabla tjänster. Genom standardiserade strukturer, metoder och namngivning säkerställs en gemensam upplevelse för utvecklare som använder tjänster från många olika API-leverantörer.

Ett API:s dokumentation kan delas in i två kategorier:

  • API dokumentation – API dokumentation kan ses som manualen för ett API. Den talar om för API-konsumenter hur man använder API:et. API dokumentation är avsedd för människor, vanligtvis utvecklare, att läsa och förstå. Att tillhandahålla dokumentation som är väldesignad, heltäckande och lätt att följa är avgörande när det gäller att säkerställa att utvecklare har en bra upplevelse av API:et. API dokumentationen brukar inkludera en snabbstartsguide, tutorials och interaktiv dokumentation så att utvecklare kan prova att anropa API:et. 
  • API specifikation – API specifikationen ger en bred förståelse för hur ett API beter sig och hur API:er länkar till andra API:er. Den förklarar hur API:et fungerar och vilka resultat man kan förvänta sig när man använder API:et. En API specifikation är avsedd för både människor och maskiner. Ett exempel på en standard för API specifikationen är OpenAPI Specification. 

I vissa fall finns ingen tydlig gräns mellan vad som återfinns i dokumentationen och vad som återfinns i specifikationen. Därför ska uppdelningen nedan i API dokumentation och API specifikation inte ses som ett måste. Dock gäller kraven oberoende av vart de finns dokumenterade. För mer information om dokumentation för API:er se Understanding the Differences Between API Documentation, Specifications, and Definitions. 

I regel BÖR (DOK.01) dokumentationen och specifikationen för ett API finnas allmänt tillgänglig online. Undantaget är om det finns juridiska, säkerhetsmässiga eller affärsmässiga skäl att inte tillgängliggöra dokumentationen. Vidare BÖR (DOK.02) ett API:s dokumentation och specifikation finnas sökbara via Sveriges dataportal. 

API dokumentation

Dokumentationen för ett API SKALL (DOK.03) innehålla följande 

  • Om API 
  • Användarvillkor 
  • Datamodell för representation av resurser 
  • Krav på autentisering 
  • Livscykelhantering och versionshantering
  • Kontaktuppgifter 

Följande är generella riktlinjer på dokumentation av REST API:er 

  • Dokumentationen och i synnerhet specifikationen SKALL (DOK.04) ses som ett kontrakt mellan designer och utvecklare samt mellan producent och konsument av API:et. 
  • Dokumentationen SKALL (DOK.05) versionshanteras tillsammans med API:et. 
  • Dokumentationen BÖR (DOK.06) finnas på både svenska och engelska. 
  • Dokumentationen av ett API BÖR (DOK.07) innehålla övergripande information om API:et. 
  • Ett API:s servicenivå SKALL (DOK.08) finnas tydligt beskriven i dokumentationen. 
  • Kända problem och begränsningar SKALL (DOK.09) finnas tydlig beskrivna i dokumentationen. 
  • Om det är känt SKALL (DOK.10) tidpunkt för när API:et tas ur bruk anges i dokumentationen. 

Följande gäller för API:ets specifika resurser, operationer och förväntade resultat.  

  • Avsikten och beteendet hos API:et SKALL (DOK.11) beskrivas så utförligt och tydligt som möjligt. 
  • Ett API:s resurser och de möjliga operationer som kan utföras på resursen SKALL (DOK.12) beskrivas så utförligt och tydligt som möjligt 
  • Förväntade returkoder och felkoder SKALL (DOK.13) vara fullständigt dokumenterade. 
  • Krav på autentisering SKALL (DOK.14) anges i dokumentationen 
  • I dokumentationen av API:et SKALL (DOK.15) exempel på API:ets fråga (en:request) och svar (en:reply) finnas i sin helhet. 

Notera att detta nödvändigtvis inte finns i API dokumentationen utan kan återfinnas i API specifikationen, se nästa kapitel. 

API specifikation

REST API:er SKALL (DOK.16) ha en API specifikation som bör kunna generera en datamodell för representation av API:ets resurser. API specifikation BÖR (DOK.17) dokumenteras med den senaste versionen av OpenAPI Specification. I sällsynta fall kan man behöva göra ett undantag att inte använda OpenAPI för att specificera ett API. Exempelvis i de fall det finns en erkänd och spridd branschstandard för att specificera API:er. 

API specifikationen BÖR (DOK.18) beskrivas med antingen JSON eller YAML. 

En API specifikation SKALL innehålla 

  • Ett API:s resurser och de möjliga operationer som kan utföras på resursen SKALL (DOK.19) beskrivas så utförligt och tydligt som möjligt 
  • Förväntade returkoder och felkoder SKALL (DOK.20) vara fullständigt dokumenterade. 
  • Krav på autentisering SKALL (DOK.21) anges i specifikationen 

Varje ny major-version av ett API, enligt versionshanteringsavsnittet, SKALL (DOK.22) följas av en ny API specifikation. Till exempel om ett API tillgängliggör och hanterar tre major version så måste det finnas tre API specifikationer, en för varje version.

API specifikationen SKALL (DOK.23) återfinnas under API-roten, det vill säga

{protokoll}://{domännamn}/{API}/{version}/

Om API specifikationen specificeras med OpenAPI SKALL (DOK.24) roten till specifikationen namnges med openapi.yaml eller openapi.json, se exemplet nedan

{protokoll}://{domännamn}/{API}/{version}/openapi.yaml 

{protokoll}://{domännamn}/{API}/{version}/openapi.json