REST API

I sitt sammanhang

REST är en arkitekturstil, inte ett produktformat och inte en synonym till ”JSON över HTTP”. Ett API kan använda HTTP och JSON men ändå motverka REST-idéerna genom sessionsberoende anrop, otydliga resurser eller metoder vars beteende strider mot HTTP-semantiken.

Resursen är viktigare än endpointen

GET /assets/42 hämtar en representation av tillgång 42. PUT kan ersätta ett avsett tillstånd, POST kan låta resursen bearbeta innehåll och DELETE begär att kopplingen till resursen tas bort. RFC 9110 definierar metodernas semantik, inklusive vilka som är säkra och idempotenta. Affärsreglerna måste fortfarande beskrivas av API-kontraktet.

Ett hållbart API publicerar inte databasen. Det publicerar en förmåga med en ägare.

Kontraktet har fler lager än JSON

• Identitet: stabila URI:er och nycklar för de resurser konsumenten faktiskt behöver.
• Semantik: metod, statuskod, fältbetydelse, enhet och tillåtna tillståndsövergångar.
• Drift: gränser, paginering, timeout, retry, idempotency keys och observerbarhet.
• Förändring: kompatibilitetsregler, deprecation, versionspolicy och konsumentdialog.
• Tillit: TLS, autentisering, auktorisering, dataminimering och loggpolicy.

OpenAPI gör ytan maskinläsbar

OpenAPI Specification beskriver ett språkagnostiskt gränssnitt till HTTP API:er så att människor och verktyg kan förstå tjänstens förmågor utan källkod eller trafikanalys. Beskrivningen kan driva dokumentation, klientgenerering och tester. Den är dock inte ensam sanningen om verksamhetsbetydelse eller produktionsbeteende. Kontraktstester och driftmätning behövs för att verifiera att implementationen håller löftet.

REST API eller händelseflöde?

Använd ett REST API när en konsument vill fråga efter eller påverka ett känt resursläge och behöver ett direkt svar. Använd exempelvis MQTT när producenten ska meddela att något har hänt utan att känna mottagarna. Mogna arkitekturer kombinerar ofta båda: händelsen signalerar en förändring, API:t ger en auktoritativ aktuell representation.

Granskning före publicering

1. Kan en utomstående namnge resursen och dess ägare?
2. Följer metoder, statuskoder och caching avsedd HTTP-semantik?
3. Är retry säkert, och är idempotens uttryckligen designad?
4. Beskriver OpenAPI lyckade svar, kända fel och säkerhetskrav?
5. Finns kompatibilitetstest, deprecation-fönster och användningsmätning?
6. Exponeras minsta nödvändiga data till minsta nödvändiga behörighet?

Relaterade begrepp

Relaterat: API, JSON, datastyrning och informationsmodellering.