Om REST API-profilen

Profilen riktar sig främst till API-designers och API-utvecklare som arbetar med framtagande av nya REST API:er eller ändrar i befintliga för att t.ex. förbättra funktionalitet, användbarhet, läsbarhet eller säkerhet.

Profilen ska användas i frågeställningar som uppstår vid framtagandet av nya/utveckling av befintliga API:er och ger en bild över vilka förväntningar som kan finnas på API:er som ska verka nationellt mellan organisationer och myndigheter.

Vidare så kan nyttjande av denna profil leda till en generellt högre standard och kvalitet på API:er, både på dokumentationen och själva API:et. Detta underlättar för både producenter och konsumenter.

REST API-profilen uppdateras kontinuerligt och den senaste versionen finns tillgänglig online. Aktuell version av profilen samt tidigare versioner finns tillgängliga som nedladdningsbara filer nederst på denna sida.

Som bilaga till denna profil finns från och med version 1.1.0 ett Excel-dokument som avser att underlätta avstämning mot respektive krav och för att ge en översikt till hur ett API uppfyller denna REST API-profil. Bilagan finns tillgänglig som nedladdningsbar fil nederst på denna sida.

Nyckelord i profilen

I denna profil använder vi endast följande nyckelord: SKALL, BÖR och KAN samt SKALL INTE och BÖR INTE. Nyckelorden ska tolkas enligt RFC 2119 enligt nedanstående tabell.

Nyckelord i profilNyckelord enligt RFC2119Betydelse
SKALL, SKALL INTE

MUST, MUST NOT

SHALL, SHALL NOT

REQUIRED

Detta är ett absolut krav för att uppfylla profilen.
BÖR, BÖR INTE

SHOULD, SHOULD NOT

RECOMMENDED

Då detta nyckelord används är det rekommenderat att uppfylla detta krav men det är inte obligatoriskt.
KAN

MAY

OPTIONAL

Detta krav kan användas.

Om man väljer att följa profilen, så är det viktigt förhålla sig till skrivelserna i tabellen ovan eftersom det finns indirekta beroenden mellan de olika sektionerna i profilen.

Nyckelorden används för att uttrycka ett krav, och efterföljs av en identifikation av kravet på formen (XXX.YY) där XXX är en förkortning till avsnittet där kravet ingår och YY avser en stigande numrering av kraven inom avsnittet.

Medvetna val

  • Profilen fokuserar på att använda HTTP REST API:er som grund för design. 
    • REST API är ett sätt att bygga ett API baserat på den funktionalitet som finns i HTTP (HyperText Transfer Protocol). Vi har valt REST som grund för profilen på grund av en rad olika orsaker. 
    • REST, står för Representational State Transfer och är i grund och botten en standardiserad mjukvaruarkitekturstil, som består av en speciell typ av API:er, som för branschen är känd och använd. 
    • REST förlitar sig på ett tillståndslöst klient-serverprotokoll och i nästan alla fall kommer det att vara HTTP. Tidigare förlitade sig utvecklare främst på SOAP för att implementera API:et i webbtjänster, men på senare år har REST blivit utvecklares val på grund av dess enkelhet och skalbarhet. REST skapades för att behandla objekt på serversidan som resurser som i sin tur kan skapas, uppdateras och raderas. REST kan användas av praktiskt taget alla programmeringsspråk. 
    • För mer information se: En introduktion till REST 
  • REST profilen är främst fokuserad till extern åtkomst, där graden av interoperabilitet i den offentliga sektorn behöver stärkas, men det går lika bra att applicera profilen för enbart intern åtkomst. Här är det lämpligt att låta verksamhetsbehovet styra. 
  • I de första versionerna av profilen, så kommer området språkbruk inte att behandlas, utan det kommer att ske i en senare version. 
  • De exempel som förekommer i profilen kan vara både existerande och fiktiva. Syftet är att förtydliga texten som omger exemplet, och översyn kommer att ske senare för att göra dem mer enhetliga och funktionella.
  • Vissa uttryck kan förekomma på både svenska och engelska beroende på vart i texten det förekommer.

Versionshantering

Nedan specificeras de förändringar sedan profilen publicerades första gången.

VersionDatumKommentar
1.0.02022-07-11Första publicering efter remissgenomgång.
1.1.02023-06-29

Uppdaterat följande:

  • avsnittet Säkerhet införd.
  • förtydligat i formatering gällande kod, viktiga benämningar och annat.
  • tagit bort blanksteg som giltig indikation att tidselementet startar i avsnittet Datum- och tidsformat.
  • förtydligat att det är camelCase eller snacke_case som ska användas som namnsättningskonvention för söksträng i message och för body i request/response, och att det är viktigt att det är konsekvent.
  • för API request header Authorization ska inte ‘Användarnamn + Lösenord’ eller ’Basic Auth’ användas.
  • HTTP response koder förhåller sig till RFC 7231, inte RFC 7807.
  • Cachning refererar till nyare RFC 9111, istället för den gamla RFC 7234
  • ’Användbara responseheaders’ är borttagna från Cache-Control avsnittet, och RFC får agera källa.
  • Infört en formatmallsbeskrivning som visar betydelsen av de olika formateringarna av text som återfinns i profilen.
  • Alla krav har erhållit ett identifikationsnummer. Detta identifikationsnummer återfinns även i den avstämningsfil (Excel) som följer som komplement till version 1.1.0 av REST API profilen. Denna avstämningsfil fylls i per API.

Formatmall

Följande formateringar finns i profilen för att underlätta läsandet och förtydliga innehållet. 

FormatBetydelse
fetNyckelord från RFC 2119, rubriker, ingress.
kursivViktiga ord, definitioner.
understrykningLänkar.
markerad textAttribut från kod och exempelvärden.
kodblock
Komplett kodexempel.

infoblock

Text som behöver lyftas/belysas i texten.

formatblock

Beskrivning av format.

Resurser

DatumResursKommentar
2023-06-29REST API-profil v.1.1.0(pdf,811 kb)Version 1.1.0 av REST APi-profilen
2023-06-29Avstämning REST API profil v.1.1.0(Excel,65kb)Avstämningsfil (Excel) som följer som komplement till version 1.1.0 av REST API-profilen.
2022-07-11REST API-profil v.1.0.0(pdf,692 kb)Första utgåvan av REST API-profilen. Version 1.0.0