WORDS

Webb-api:er: Rest och HTTP

I förra inlägget introducerade jag webb-api:er och Soap, det senare ett gediget standardiserat protokoll med vilket man kan skapa det förra. Som kontrast till Soap ska vi i det här lägget översiktligt gå igenom Rest, en mindre formell, mer minimalistisk standard. En api-arkitektur byggd utefter dessa principer kallas Rest-ful (ofta skrivet som "RESTful").

För att kunna förstå Rest, så krävs också förståelse av några grundkoncept inom HTTP, eftersom dom två är nära relaterade. Dom utvecklades faktiskt tillsammans.

HTTP

HTTP är ett protokoll, som låter en klient göra förfrågningar till en server. Ett HTTP-anrop (eng. request) innehåller:

  1. Metod, också kallat "verb": GET, POST, PUT, DELETE och några mer esoteriska metoder. Beskriver vad som ska göras: hämta, lägga till, uppdatera eller radera.
  2. Url: Vilken resurs gäller metoden? Vilken information ska hämtas, uppdateras eller raderas?
  3. Headers: Metadata, som på vilken form man vill ha svaret i (t.ex. skrivet språk, programspråk, teckenkodning).
  4. Body: Innehållet som skickas med anropet. Används bara vid POST och PUT.

Svaret (eng. response) innehåller headers och body.

Det som är särskilt viktigt för oss är metoderna, som direkt mappas till hur vi designar vårt Rest-api.

Rest

Varför?

Innan vi går in på hur man implementerar Rest, så ska vi nämna några fördelar gentemot Soap.

  • Kan välja ett enkelt och minimalt dataöverföringsformat, såsom Json. (Soap tenderar att bli väldigt stort.)
  • Klienten skickar med all nödvändig information i varje anrop, vilket gör att det är lättare att skala upp från en server till flera servrar. Om all nödvändig information finns direkt i anropet, så måste inte servern hålla användarens state i minnet.
  • Anrop som bara hämtar data kan effektivt cachas. På så vis kanske klienten slipper göra anropet över huvud taget.
  • När vi kommunicerar över internet, är det ofta enklast att använda HTTP, och varför då inte utnyttja den arkitektur som HTTP är byggd för.

Resurser och metoder

Centralt i Rest är resurser. Varje url motsvarar en resurs, och beroende på vilken metod (HTTP-metod) man använder, så görs olika saker. En resurs kan antingen vara ett enskilt element, eller en samling.

HTTP-metoder Samling, exempelvis https://api.example.com/resources/ Element, exempelvis https://api.example.com/resources/item5
GET Lista information om elementen i samlingen, och kanske ytterligare lite information. Hämta en representation av detta element i samlingen.
PUT Ersätt hela samlingen med en annan samling. Används sällan. Ersätt detta element i samlingen, eller om det inte existerar, skapa det.
PATCH Används sällan. Uppdatera elementet i samlingen. Borde säkert användas mer än vad det gör i praktiken - ofta används helt enkelt PUT.
POST Skapa ett nytt element i samlingen. Det nya elementets url sätts automatiskt. Används sällan.
DELETE Radera hela samlingen. Används sällan. Radera detta element i samlingen.

Sammanfattningsvis

  • Använd rätt HTTP-metod:
    • GET när man bara ska hämta information och inget ändras
    • PUT när något ska ersättas med en ny version
    • PATCH när en del av ett element ska uppdateras
    • POST när man ska lägga till ett element
    • DELETE när något ska raderas
    • Och vet man inte vad man ska använda, så är det bra att använda POST som slask
  • Fundera en del över url:en. Den bildar en hierarki, och ett bra system är ofta: /api/område/samling/123/undersamling/456. Varje applikation har sina egna behov här.