REST API

I kapitel 5 af sin afhandling fra 2000 udleder Roy Fielding REST ved at tilføje begrænsninger én ad gangen: klient-server, tilstandsløshed (hver forespørgsel indeholder alt, hvad der skal til for at forstå den), svar der kan caches, en ensartet grænseflade, et lagdelt system og valgfri code-on-demand. Den ensartede grænseflade har fire delkrav: identifikation af ressourcer, behandling af ressourcer via repræsentationer, selvbeskrivende beskeder og hypermedie som motor for applikationens tilstand (HATEOAS), dvs. at klienter finder de næste handlinger via links i svarene frem for via viden udefra. De fleste API'er, der markedsføres som REST, ignorerer hypermedie, hvilket Fielding offentligt kritiserede i 2008; Richardson Maturity Model inddeler API'er fra niveau 0 (ét endpoint, RPC over HTTP) over ressourcer og HTTP-verber til niveau 3 (hypermediekontroller).

Den gængse kortlægning bruger HTTP's semantik direkte. GET henter og er sikker og kan caches; POST til en samling opretter en underordnet ressource, svarer med 201 Created og en Location-header og er ikke idempotent; PUT erstatter en ressource og er idempotent; PATCH (RFC 5789) anvender en delvis ændring, udtrykt enten som JSON Merge Patch (RFC 7396) eller som en liste af JSON Patch-operationer (RFC 6902); DELETE fjerner. Tabte opdateringer forhindres med ETags og If-Match, besvaret med 412 Precondition Failed ved konflikt. Fejl returneres i stigende grad som problem details (application/problem+json, RFC 9457, som afløste RFC 7807), og paginering bruger cursorer eller Link-headere (RFC 8288). Fordi POST ikke er idempotent, kræver sikre gentagelser en idempotensnøgle, som klient og server er enige om.

Kontrakterne beskrives med OpenAPI Specification, der voksede ud af Swagger 2.0 og blev overdraget til Linux Foundations OpenAPI Initiative i 2015; version 3.1 afstemte sin skemadialekt med JSON Schema 2020-12. Beskrivelsen driver dokumentation, generering af klientkode, kontrakttest og validering af forespørgsler i gateways.

Designet med én URL pr. ressource gør objekt-id'er synlige i hver forespørgsel, og derfor er Broken Object Level Authorization API1 i OWASP API Security Top 10 (2023): at ændre /bookings/42 til /bookings/43 skal afvises af en ejerskabskontrol på serveren, og at skifte til UUID'er gør kun gætteriet sværere uden at rette fejlen. PUT- og PATCH-endpoints, der binder forespørgslens indhold direkte på en datamodel, åbner for mass assignment af felter som isAdmin (en del af API3:2023), og headere til metodeoverstyring som X-HTTP-Method-Override kan omgå adgangsregler skrevet pr. HTTP-metode. REST står i kontrast til GraphQL, hvor ét endpoint modtager forespørgsler formet af klienten, og til gRPC, der udstiller procedurer frem for ressourcer.