Om REST API-profilen

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.

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.

Formatmall

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

kodblock

Resurser