REST-API

Delarna som spelar roll i vardagen

Resurser, inte handlingar. URL:en namnger ett ting – /ordrar, /ordrar/42 – och metoden namnger operationen. GET /ordrar/42 läser den, DELETE /ordrar/42 tar bort den. Endpoints som /hamtaOrderMedId fungerar utmärkt men är inte vad REST betyder.

Tillståndslöshet. Servern minns ingenting från tidigare anrop, så varje anrop bär sin egen autentisering, oftast en token i headern Authorization. Det är det som gör att vilken server som helst bakom en lastbalanserare kan besvara vilket anrop som helst.

Statuskoder bär betydelse. 200 lyckades, 201 skapad, 400 anropet var felformat, 401 inte inloggad, 403 inloggad men inte behörig, 404 resursen finns inte, 429 för många anrop, 500 servern gick sönder. Ett API som svarar 200 med {"error": ...} i kroppen tvingar varje klient att tolka innehållet innan den kan skilja framgång från fel.

Idempotens. GET, PUT och DELETE ska ge samma sluttillstånd oavsett om de skickas en eller fem gånger, medan POST normalt inte gör det. Det är därför ett omförsök av en misslyckad betalning behöver en idempotensnyckel.

Missuppfattningen

Det mesta som kallas REST-API är inte REST i strikt mening. Roy Fieldings definition omfattar hypermedia – svar som länkar till nästa möjliga handlingar – och nästan ingenting implementerar det. Vad branschen faktiskt menar med "REST-API" är JSON över HTTP med vettiga URL:er och verb. Det är helt i sin ordning, och värt att känna till när en purist invänder.

När något annat passar bättre

GraphQL låter klienten begära exakt de fält den behöver i ett enda anrop, vilket passar vyer som annars hade krävt sex anrop. Priset är cachning och komplexitet. Webhooks vänder på riktningen för händelser du annars hade fått fråga efter upprepade gånger. Och när det gäller versionering är det ärliga rådet att bestämma sig tidigt – att lägga /v1/ i sökvägen kostar ingenting nu och besparar dig en smärtsam migrering när ett svarsformat måste ändras.