Free Press

REST API’er giver dig mulighed for at udvikle enhver form for webapplikation med alle mulige CRUD-operationer (oprette, hente, opdatere og slette). REST-retningslinjerne foreslår, at man bruger en bestemt HTTP-metode til en bestemt type opkald til serveren (selv om det teknisk set er muligt at overtræde denne retningslinje, men det frarådes stærkt).

Brug nedenstående oplysninger til at finde en passende HTTP-metode til den handling, der udføres af API’et.

Table of ContentsHTTP GETHTTP POSTHTTP PUTHTTP DELETEHTTP PATCHSummaryGlossary

HTTP GET

Brug GET-forespørgsler kun til at hente ressourcerepræsentation/information – og ikke til at ændre den på nogen måde. Da GET-forespørgsler ikke ændrer ressourcens tilstand, siges disse at være sikre metoder. Desuden bør GET-API’er være idempotente, hvilket betyder, at flere identiske anmodninger skal give det samme resultat hver gang, indtil en anden API (POST eller PUT) har ændret ressourcens tilstand på serveren.

Hvis Request-URI’en henviser til en dataproducerende proces, er det de producerede data, der skal returneres som entitet i svaret, og ikke processens kildetekst, medmindre denne tekst tilfældigvis er processens output.

For en given HTTP GET API skal den, hvis ressourcen findes på serveren, returnere HTTP-svarkode 200 (OK) – sammen med svarteksten, som normalt er enten XML- eller JSON-indhold (på grund af deres platformsuafhængige karakter).

Hvis ressourcen IKKE findes på serveren, skal den returnere HTTP-svarkode 404 (NOT FOUND). Tilsvarende, hvis det konstateres, at selve GET-anmodningen ikke er korrekt udformet, så skal serveren returnere HTTP-svarskode 400 (BAD REQUEST).

Eksempel på anmodningens URI’er

• HTTP GET http://www.appdomain.com/users
• HTTP GET http://www.appdomain.com/users?size=20&page=5
• HTTP GET http://www.appdomain.com/users/123
• HTTP GET http://www.appdomain.com/users/123/address

HTTP POST

Brug POST-API’er til at oprette nye underordnede ressourcer, f.eks, en fil er underordnet en mappe, der indeholder den, eller en række er underordnet en databasetabel. Når man taler strengt i REST-termer, bruges POST-metoder til at oprette en ny ressource i samlingen af ressourcer.

Hvis en ressource er blevet oprettet på origin-serveren, SKAL svaret være HTTP-svarkode 201 (Created) og indeholde en entitet, der beskriver status for anmodningen og henviser til den nye ressource, og en Location-header.

Flere gange resulterer den handling, der udføres af POST-metoden, måske ikke i en ressource, der kan identificeres ved hjælp af en URI. I dette tilfælde er enten HTTP-svarkode 200 (OK) eller 204 (No Content) den passende svarstatus.

Svar til denne metode kan ikke lagres i cache, medmindre svaret indeholder passende Cache-Control- eller Expires-hovedfelter.

Bemærk, at POST hverken er sikkert eller idempotent, og påberåbelse af to identiske POST-anmodninger vil resultere i to forskellige ressourcer, der indeholder de samme oplysninger (undtagen ressource-id’er).

Eksempel på anmodningens URI’er

• HTTP POST http://www.appdomain.com/users
• HTTP POST http://www.appdomain.com/users/123/accounts

HTTP PUT

Brug PUT API’er primært til at opdatere eksisterende ressource (hvis ressourcen ikke findes, kan API’et beslutte at oprette en ny ressource eller ej). Hvis en ny ressource er blevet oprettet af PUT API’et, SKAL origin-serveren informere brugeragenten via HTTP-svarkode 201 (Created)-svaret, og hvis en eksisterende ressource ændres, SKAL enten 200 (OK) eller 204 (No Content) svarkoderne sendes for at angive, at anmodningen er gennemført med succes.

Hvis anmodningen passerer gennem en cache, og Request-URI’en identificerer en eller flere aktuelt cachelagrede enheder, SKAL disse poster behandles som forældede. Svar på denne metode kan ikke bruges i cachen.

Eksempel på request-URI’er

• HTTP PUT http://www.appdomain.com/users/123
• HTTP PUT http://www.appdomain.com/users/123/accounts/456

HTTP DELETE

Som navnet siger, bruges DELETE-API’er til at slette ressourcer (identificeret ved Request-URI’en).

Et vellykket svar på DELETE-anmodninger SKAL være HTTP-svar code 200 (OK), hvis svaret indeholder en entitet, der beskriver status, 202 (Accepted), hvis handlingen er blevet sat i kø, eller 204 (No Content), hvis handlingen er blevet udført, men svaret ikke indeholder en entitet.

DELETE-operationer er idempotente. Hvis du DELETE en ressource, fjernes den fra samlingen af ressourcer. Hvis du gentagne gange kalder DELETE API på den pågældende ressource, ændres resultatet ikke – hvis du derimod kalder DELETE på en ressource anden gang, returneres der en 404 (NOT FOUND), da den allerede er blevet fjernet. Nogle vil måske hævde, at det gør DELETE-metoden ikke-idempotent. Det er et spørgsmål om diskussion og personlig mening.

Hvis anmodningen passerer gennem en cache, og Request-URI’en identificerer en eller flere aktuelt cachede enheder, SKAL disse poster behandles som forældede. Svar på denne metode kan ikke bruges til cache.

Eksempel på request-URI’er

• HTTP DELETE http://www.appdomain.com/users/123
• HTTP DELETE http://www.appdomain.com/users/123/accounts/456

HTTP PATCH

HTTP PATCH-anmodninger er til at foretage delvis opdatering af en ressource. Hvis du ser, at PUT-forespørgsler også ændrer en ressourceenhed, så for at gøre det mere klart – PATCH-metoden er det korrekte valg til delvis opdatering af en eksisterende ressource, og PUT bør kun bruges, hvis du erstatter en ressource i sin helhed.

Bemærk venligst, at der er nogle udfordringer, hvis du beslutter dig for at bruge PATCH-API’er i din applikation:

• Support for PATCH i browsere, servere og webapplikationsrammer er ikke universel. IE8, PHP, Tomcat, Django og masser af anden software har manglende eller ødelagt understøttelse for det.
• Request payload af en PATCH-anmodning er ikke ligetil, som det er for PUT-anmodning. f.eks.

  HTTP GET /users/1

  producerer nedenstående svar:

  {id: 1, username: 'admin', email: ''}

  En eksempel på en patchanmodning for at opdatere e-mailen vil se således ud:

  HTTP PATCH /users/1

  ” }
  ]

Der kan være følgende mulige operationer er pr. HTTP-specifikation.

},
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy","from": "/a/b/d", "path": "/a/b/e" }
]

Metoden PATCH er ikke en erstatning for POST- eller PUT-metoderne. Den anvender en delta (diff) i stedet for at erstatte hele ressourcen.

Summary of HTTP Methods for RESTful APIs

Nedenstående tabel opsummerer brugen af de HTTP-metoder, der er omtalt ovenfor.

Glossar

Sikre metoder

Som i HTTP-specifikationen bør GET- og HEAD-metoderne kun bruges til at hente ressource-repræsentationer – og de opdaterer/sletter ikke ressourcen på serveren. Begge metoder siges at blive betragtet som “sikre”.

Dette gør det muligt for brugeragenter at repræsentere andre metoder, såsom POST, PUT og DELETE, på en unik måde, så brugeren gøres opmærksom på, at der anmodes om en muligvis usikker handling – og de kan opdatere/slette ressourcen på serveren og bør derfor anvendes med forsigtighed.

Idempotente metoder

Udtrykket idempotent bruges mere omfattende til at beskrive en operation, der vil give de samme resultater, hvis den udføres én eller flere gange. Idempotens er en praktisk egenskab i mange situationer, da det betyder, at en operation kan gentages eller genforsøges så ofte som nødvendigt uden at forårsage utilsigtede virkninger. Med ikke-idempotente operationer kan algoritmen være nødt til at holde styr på, om operationen allerede er blevet udført eller ej.

I HTTP-specifikationen er metoderne GET, HEAD, PUT og DELETE erklæret idempotente metoder. Andre metoder OPTIONS og TRACE BØR IKKE have sideeffekter, så begge er også i sagens natur idempotente.