API Request
Request headers
Ett request BÖR (ARQ.01) skickas i UTF-8.
Alla API:er SKALL (ARQ.02) supportera följande request headers
| Header | Värde |
|---|---|
| Authorization | Om APIet kräver autentisering ska en av följande användas:
|
| Content-Type | Använd ett av följande tre format, men om ytterligare format stödjs bör man ange dessa också:
|
Alla API:er BÖR (ARQ.03) supportera följande request headers
| Header | Värde |
|---|---|
| Accept | Ett av följande BÖR (ARQ.04) användas:
|
| Accept-Charset | utf-8 |
| Date | Datum och tid då meddelandet skickades, i format definierat i RFC 3339 |
| Cache-Control | Används för att specificera direktiv som måste följas av alla cachemekanismer, t.ex. ingen cache. |
| ETag | Används för att identifiera den specifika versionen av en resurs som uppdateras för att förhindra flera användaruppdateringar. Detta borde matcha det som för närvarande är lagrat på servern. |
| Connection | För den aktuella anslutningen ska keep-alive användas. |
| Cookie | En HTTP cookie som tidigare skickats av servern. |
Payload data SKALL INTE (ARQ.05) användas i HTTP-headers.
Supporterade HTTP Request metoder
REST API-operationer baseras på standarderna för HTTP-request som definieras i RFC 7231 och RFC 5789. Ytterligare information finns att läsa i artikeln En introduktion till REST.
| HTTP metod | Beskrivning |
|---|---|
| GET | Att hämta en resurs |
| POST | Att skapa en ny resurs, eller att utföra en operation på en resurs som ändrar systemets tillstånd, t.ex. skicka ett meddelande. Används även då ingen HTTP-metod naturligt passar. |
| PUT | Ersätter en resurs med en annan som anges i begäran |
| PATCH | Delvis uppdatera en resurs |
| DELETE | Helt ta bort en resurs |
En begäran om att hämta resurser kan göras för en resurs eller för en samling.
Exempel:
https://gw.api.bolagsverket.se/foretagsinformation/v2/organisationer/{id}
För att hämta en samling organisationer skickas en begäran till namnet på resursen /organisationer
För att hämta en enda organisation skickas en begäran till identifikationen på resursen /organisationer/{id}
Enkel resurs
| HTTP metod | Resurs sökväg | Operation |
|---|---|---|
| GET | /resurs/{id} | Hämta förekomsten som motsvarar resurs-ID |
| PUT | /resurs/{id} | För att uppdatera en resursinstans genom att ersätta den - "Ta den här nya saken och lägg den där" |
| DELETE | /resurs/{id} | För att ta bort resursinstansen baserat på resursen, t.ex. id |
| PATCH | /resurs/{id} | Utför ändringar som att lägga till, uppdatera och radera till de angivna attributen. Används ofta för att utföra partiella uppdateringar av en resurs |
Samling av resurser
Följande åtgärder gäller för en samling resurser:
| HTTP metod | Resurs sökväg | Operation | Exempel |
|---|---|---|---|
| GET | /resurs | Få en samling av resursen | GET /organisationer eller GET /organisationer?filter=organisationsform eg AB |
| POST | /resurs | Skapa en ny instans av den här resursen |
Notering:
Skapa eller uppdatera flera resursinstanser i samma begäran är för närvarande inte standardiserat. Det finns faktorer som kvitto och hur man hanterar partiell framgång i en uppsättning satser som måste övervägas från fall till fall.
Idempotens
En idempotent HTTP-metod kan anropas många gånger med samma resultat. I vissa fall kommer sekundära anrop att resultera i en annan svarskod, men resursens tillstånd ändras inte. Som ett exempel, när du anropar DELETE flera gånger på samma resurs, kommer den första begäran att ta bort resursen och svaret blir 200 (OK) eller 204 (Inget innehåll). Ytterligare förfrågningar returnerar 404 (hittades inte). Det är uppenbart att svaret skiljer sig från den första begäran, men det finns ingen ändring av tillstånd för någon resurs på serversidan eftersom originalresursen redan har raderats.
| HTTP metod | Skall vara idempotent |
|---|---|
| GET | Ja |
| POST | Nej |
| PUT | Ja |
| PATCH | Nej |
| DELETE | Ja |
| HEAD | Ja |
| OPTIONS | Ja |
REST API-metoder SKALL (ARQ.06) följa den angivna idempotensen i tabellen ovan.