Hvad betyder REST API?
REST er en arkitekturstil, og et REST API bruger typisk HTTP til at arbejde med ressourcer som kunder, ordrer eller dokumenter. En ressource har en identifikation, mens en repræsentation beskriver dens aktuelle oplysninger. JSON er almindeligt, men formatet alene gør ikke et API til REST.
I praksis bruges betegnelsen bredt. Når en integration skal bygges, er den konkrete dokumentation derfor vigtigere end etiketten. Undersøg hvilke metoder, statuskoder, datakontrakter og versionsregler den pågældende tjeneste faktisk følger.
Metoden beskriver den ønskede handling
GET bruges til at hente en repræsentation. PUT kan erstatte en repræsentation, mens DELETE anmoder om fjernelse. POST bruges til behandling efter ressourcens egen kontrakt og ofte til oprettelse. PATCH bruges ofte til delvise ændringer. De præcise krav fremgår af API'ets beskrivelse.
En læsemetode bør ikke skjule en forretningsmæssig ændring. Det er også vigtigt at forstå idempotens: gentagelse af samme anmodning kan have samme tilsigtede effekt uden at returnere identisk svar. Et tidsudløb kan derfor ikke håndteres ens for alle metoder og endpoints.
Status og data skal tolkes sammen
Et HTTP-svar fortæller noget om anmodningen, men selve resultatet kan kræve yderligere kontrol. En accepteret baggrundsopgave er eksempelvis ikke nødvendigvis afsluttet endnu. Ved store lister skal integrationen håndtere pagination, så første side ikke bliver forvekslet med alle data. Tidsstempler, tomme værdier og ændrede felter skal også have kendte regler. Stateless kommunikation betyder, at anmodningen bærer den nødvendige kontekst; det betyder ikke, at serveren ikke må gemme ressourcer eller forretningsdata.
Et eksempel fra praksis
En virksomhed henter produktdata til en intern assistent. Integrationen læser alle relevante sider af produktlisten, gemmer stabile produkt-ID'er og håndterer produkter, som senere fjernes. Et opslag på et enkelt produkt bruges til at kontrollere aktuelle oplysninger før et vigtigt svar. En test med flere sider og en fjernet vare viser, om løsningen forveksler et ufuldstændigt datasæt med et komplet eller genbruger en forældet post.
Typiske faldgruber
- At kalde enhver JSON-tjeneste for REST og overse dens faktiske kontrakt.
- At tolke første side af en liste som hele datasættet.
- At behandle accepteret, gennemført og mislykket som samme status.
Det skal I afklare
- Læs metode, status og dataschema for hvert endpoint.
- Kontrollér pagination og håndtering af manglende ressourcer.
- Aftal genforsøg efter den konkrete handlings semantik.
Spørgsmål og svar
Er alle GET-kald gratis for systemet?
Nej. GET er en læsemetode, men kan stadig kræve beregning, netværk og kapacitet. Rate limits og caching er relevante, selv om kaldet ikke ændrer forretningsdata.
Betyder idempotens, at svaret altid er ens?
Nej. Det handler om den tilsigtede effekt ved gentagelse. En gentaget sletning kan eksempelvis få en anden status, fordi ressourcen allerede er fjernet, uden at skabe en ny sletteeffekt.
Kilder og videre læsning
De tekniske begreber bygger på nedenstående kilder. Eksemplerne er illustrative og viser, hvordan I kan arbejde med emnet.
- IETF: RFC 9110 HTTP Semantics ↗HTTP-metoder, status og idempotente forespørgsler.
- Microsoft: Web API design ↗Ressourcer, metodevalg og kontrakter i web-API'er.