Free Press

REST API:er gör det möjligt att utveckla alla typer av webbapplikationer med alla möjliga CRUD-operationer (skapa, hämta, uppdatera, ta bort). REST-riktlinjerna föreslår att man använder en specifik HTTP-metod för en viss typ av anrop till servern (även om det tekniskt sett är möjligt att bryta mot denna riktlinje, men det avråds starkt från att göra det).

Använd nedanstående information för att hitta en lämplig HTTP-metod för den åtgärd som utförs av API:et.

Table of ContentsHTTP GETHTTP POSTHTTP PUTHTTP DELETEHTTP PATCHSummaryGlossary

HTTP GET

Använd GET-begäranden endast för att hämta resursrepresentation/information – och inte för att modifiera den på något sätt. Eftersom GET-förfrågningar inte ändrar resursens tillstånd sägs detta vara säkra metoder. Dessutom bör GET-API:er vara idempotenta, vilket innebär att flera identiska förfrågningar måste ge samma resultat varje gång tills ett annat API (POST eller PUT) har ändrat resursens tillstånd på servern.

Om förfrågnings-URI:n hänvisar till en dataproducerande process är det den producerade datan som ska returneras som entitet i svaret och inte processens källtext, såvida inte den texten råkar vara processens resultat.

För ett givet HTTP GET API, om resursen hittas på servern, måste den returnera HTTP-svarskoden 200 (OK) – tillsammans med svarskroppen, som vanligtvis är antingen XML- eller JSON-innehåll (på grund av deras plattformsoberoende natur).

Om resursen INTE hittas på servern måste den returnera HTTP-svarskoden 404 (NOT FOUND). På samma sätt, om det konstateras att själva GET-förfrågan inte är korrekt utformad ska servern returnera HTTP-svarskoden 400 (BAD REQUEST).

Exempel på URI:er för begäran

• 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

Använd POST API:er för att skapa nya underordnade resurser, t.ex, en fil är underordnad en katalog som innehåller den eller en rad är underordnad en databastabell. När man talar strikt i termer av REST används POST-metoder för att skapa en ny resurs i resurssamlingen.

Om en resurs har skapats på ursprungsservern bör svaret vara HTTP-svarskod 201 (Created) och innehålla en entitet som beskriver statusen för begäran och hänvisar till den nya resursen samt en Location-huvudrubrik.

Många gånger kan det hända att den åtgärd som utförs av POST-metoden inte resulterar i en resurs som kan identifieras med en URI. I detta fall är antingen HTTP-svarskod 200 (OK) eller 204 (No Content) den lämpliga svarsstatusen.

Svar till den här metoden kan inte lagras i cacheminnet, såvida inte svaret innehåller lämpliga Cache-Control- eller Expires-huvudfält.

Bemärk att POST varken är säkert eller idempotent, och att åberopande av två identiska POST-begäranden kommer att resultera i två olika resurser som innehåller samma information (med undantag för resurs-id).

Exempel på begäran URI:er

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

HTTP PUT

Använd PUT API:er i första hand för att uppdatera en befintlig resurs (om resursen inte existerar kan API:erna besluta om att skapa en ny resurs eller inte). Om en ny resurs har skapats av PUT API:et, MÅSTE ursprungsservern informera användaragenten via HTTP-svarskoden 201 (Created)-svaret och om en befintlig resurs ändras, bör antingen 200 (OK) eller 204 (No Content) svarskoderna skickas för att indikera att begäran har slutförts med framgång.

Om begäran passerar genom ett cacheminne och Request-URI identifierar en eller flera enheter som för närvarande lagras i cacheminnet, bör dessa poster behandlas som inaktuella. Svar på den här metoden kan inte lagras i cache.

Exempel på begäran-URI:er

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

HTTP DELETE

Som namnet antyder används DELETE API:er för att radera resurser (identifierade av Request-URI).

Ett lyckat svar på DELETE-förfrågningar SKA vara HTTP-svar code 200 (OK) om svaret innehåller en entitet som beskriver statusen, 202 (Accepted) om åtgärden har ställts i kö, eller 204 (No Content) om åtgärden har utförts men svaret inte innehåller någon entitet.

DELETE-operationer är idempotenta. Om du DELETE en resurs tas den bort från samlingen av resurser. Upprepade anrop av DELETE API på den resursen ändrar inte resultatet – om du däremot anropar DELETE på en resurs en andra gång returneras en 404 (NOT FOUND) eftersom den redan har tagits bort. Vissa kan hävda att det gör DELETE-metoden icke idempotent. Det är en fråga om diskussion och personlig åsikt.

Om begäran passerar genom en cache och Request-URI identifierar en eller flera enheter som för närvarande finns i cacheminnet, SKA dessa poster behandlas som inaktuella. Svar på den här metoden kan inte lagras i cache.

Exempel på begäran-URI

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

HTTP PATCH

HTTP PATCH-förfrågningar är till för att göra en partiell uppdatering av en resurs. Om du ser att PUT-förfrågningar också ändrar en resursenhet, så för att göra det tydligare – PATCH-metoden är det korrekta valet för att delvis uppdatera en befintlig resurs, och PUT bör endast användas om du ersätter en resurs i sin helhet.

Vänligen notera att det finns vissa utmaningar om du bestämmer dig för att använda PATCH-API:er i din applikation:

• Stödet för PATCH i webbläsare, servrar och ramar för webbapplikationer är inte universellt. IE8, PHP, Tomcat, Django och många andra programvaror saknar eller har bristfälligt stöd för det.
• Nyttolasten för en PATCH-förfrågan är inte lika enkel som för en PUT-förfrågan, t.ex.

  HTTP GET /users/1

  producerar nedanstående svar:

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

  Ett exempel på en patchförfrågan för att uppdatera e-postmeddelandet kommer att se ut så här:

  HTTP PATCH /users/1

  ” }
  ]

Det kan finnas följande möjliga operationer enligt HTTP-specifikationen.

},
{ "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 ersätter inte metoderna POST eller PUT. Den tillämpar ett delta (diff) i stället för att ersätta hela resursen.

Sammanfattning av HTTP-metoder för RESTful API

Nedanstående tabell sammanfattar användningen av de HTTP-metoder som diskuterats ovan.

Glossar

Säkra metoder

Enligt HTTP-specifikationen ska GET- och HEAD-metoderna endast användas för att hämta resursrepresentationer – och de uppdaterar/raderar inte resursen på servern. Båda metoderna anses vara ”säkra”.

Detta gör det möjligt för användaragenter att representera andra metoder, t.ex. POST, PUT och DELETE, på ett unikt sätt så att användaren blir medveten om att en eventuellt osäker åtgärd begärs – och de kan uppdatera/radera resursen på servern och bör därför användas med försiktighet.

Idempotenta metoder

Uttrycket idempotent används mer omfattande för att beskriva en operation som ger samma resultat om den utförs en eller flera gånger. Idempotens är en praktisk egenskap i många situationer, eftersom den innebär att en operation kan upprepas eller prövas på nytt så ofta som nödvändigt utan att orsaka oavsiktliga effekter. Med icke idempotenta operationer kan algoritmen behöva hålla reda på om operationen redan utförts eller inte.

I HTTP-specifikationen deklareras metoderna GET, HEAD, PUT och DELETE som idempotenta metoder. Andra metoder, OPTIONS och TRACE, bör inte ha några sidoeffekter, så båda är också idempotenta i sig.