Begrepp

Ett API (Application Programming Interface) är en uppsättning definitioner och protokoll för att bygga och integrera applikationsprogramvara. REST (Representational State Transfer) i sin tur är en arkitekturstil som bygger på vanliga internet standarder och möjliggör interaktion med andra webbtjänster. Nedan beskrivs de mest central begreppen som används i samband med REST API:er.

Resurs

För att utforma ett användbart och rent API bör systemet delas upp i logiska grupperingar (ofta kallade modeller eller resurser). I de flesta fall är resurserna "substantiv" i ett system. 

I grunddatadomänen Företag kan resurserna till exempelvis vara organisationer, personer och firmateckningsalternativ. 

Genom att dela upp system i dessa logiska områden möjliggör det en ren separation av problem (t.ex. fungerar funktioner kopplade till organisationer endast på organisationer). Det säkerställer att varje del av data som returneras från ditt API är det minsta som det behöver vara för att uppfylla klientkravet (t.ex. när du ber om organisationer får du inte också tillbaka årsredovisningar).

Identifierare

Varje resurs som är tillgänglig i ditt system (t.ex. varje organisation eller varje person) måste kunna identifieras unikt i systemet. Detta är ett viktigt element i API:ets anammande av REST, möjligheten att individuellt adressera alla objekt i systemet och lagra dessa identifierare för senare användning. 

Identifierare till en resurs kan vara något av följande:

NamnExempel
numerisk/organisationer/5569010111
sträng/landskoder/sverige
UUID (RFC 4122)/medarbetare/0d047d80-eb69-4665-9395-6df5a5e569a4
datum (kort form)/datum/2018-09-17

Så länge identifieraren är unik i programmet kan det vara vilken teckensträng eller nummer som helst.

Representation

Ett nyckelkoncept i REST API design är idén om representation av en resurs vid en viss tidpunkt. 

När du ber systemet om företagsinformation får du en representation av organisationen, t.ex. 

HTTP 1.1 GET /organisationer/5568108988
Accept: application/json
200 OK
Content-Type: application/json
organisationslista: [
  {
    "namn" : "Volvo Cars AB",
    "organisationsnummer" : "5568108988",
    "bolagsform" : "Aktiebolag",
    "registreringsar" : "2010"
  }
]

Avsikten är att den här representationen kan ändras med tiden när systemet och data i ändras. Ett framtida anrop till samma endpoint kan ge en annan representation, t.ex. om organisationen bytt organisationsform. 

Det är också möjligt att begära en helt annan representation av samma resurs om systemet stöder den. Det kan till exempel finnas ett fall där du behöver en PDF-version av den här företagsinformationen och detta kan understödjas från producentsidan genom att tillåta en begäran om en annan representation via Accept header:
 

HTTP 1.1 GET /organisationer/5568108988
Accept: application/pdf

200 OK
Content-Type: application/pdf

...<BINARY CODE>...

Mer information om representationer och hur du stöder dem finns i avsnittet API Message.

Operationer

För att utföra en operation på en resurs behöver man ange en HTTP-metod följt av sökvägen till resursen.

Operationer avgör hur API kan användas och det finns inget annat sätt att nyttja API än genom de operationer den stödjer.

En operation definieras av:

  • En HTTP-metod och
  • en resurssökväg

Exempel:

GET /organisationer

GET /organisationer/5568108988

DELETE /organisationer/5568108988