När man designar sitt API är det viktigt att tänka på att man använder rätt verb på rätt ställe. Detta kan ibland orsaka viss förvirring och även leda till att API:et används felaktigt och i värsta fall att data försvinner eller förändras på ett icke önskvärt sätt. Nedan ska jag försöka bena ut hur man använder de vanligaste verben. Vi utgår ifrån att vi har ett API som hanterar flygplan och dess säten /airplanes/{airplaneId}/seats och vi låtsas att ett säte kan ha följande attribut
{
”size”: ”medium”,
”gadgets”:[{”screen”,”usb”,”garbage-bag”,life-jacket}],
”id”: 35
}
GET
Verbet GET används som det låter för att hämta information. Information kan hämtas antingen direkt på en resurs eller på ett id. GET: /airplanes/4567/seats ger tillbaka alla säten som finns i flygplanet med id 4567. Man kan även använda sig av query params för filtrering. Tex GET: /airplanes/4567/seats?color=blue returnerar alla säten som har färgen blå. Lämpliga HTTP – statuskoder för detta kan vara 200 vid träff, 204 om inga blå säten finns. Om man istället gör en GET på /airplanes/4567/seats/35 så skulle man få tillbaka endast ett säte, det med ID 35. Här kan man tänkas få statuskod 200 om det finns eller 404 om resursen inte finns.
POST
POST används för att skapa nya instanser av en resurs. POST: /airplanes/4567/seats skulle alltså skapa ett nytt säte i flygplanet med id 4567.
{
"color": "blue",
"size": "medium",
"gadgets": [{
"screen",
"usb"
}]
}En POST med ovanstående body skulle alltså skapa ett nytt säte med blå färg, storlek medium och ett par gadgets. ID attributet skickas inte in utan skapas helst av systemet som tar emot datat. Detta kan med fördel returneras i svaret. Här kan man förvänta sig statuskod 201 Created eller 202 Accepted. Även listor av objekt kan skickas in vid POST och flera nya objekt skapas vid samma anrop.
POST kan ibland användas till mycket annat också som att skicka formulär eller inloggningsinformation men vid apidesign så bör man tänka att det ska användas för att skapa nya objekt.
PUT
PUT görs på ett befintligt objekt och används för att uppdatera ett helt objekt. Om vi gör en put på /airplanes/{airplaneId}/seats/35 så betyder det att vi skriver över det befintliga sätet med ID 35.
Säg att vi gör en PUT på säte 35 och använder nedanstående body
{
"color": "blue",
"size": "medium",
"gadgets": [{
"screen",
"usb"
}]
}Då betyder det att vi tar bort flytväst och papperskorg från det här sätet.
Lämpliga OK statuskoder vid PUT är 200 OK eller 204 No content.
PATCH
PATCH görs också det på ett eller flera befintliga objekt men till skillnad från PUT så betyder det att man bara uppdaterar delar av ett objekt så om vi här gör en put på /airplanes/4567/seats/35 med följande body
{
"color":"red"
}så betyder det att vi enbart uppdaterar attributet color, resterande attribut förblir intakta. Statuskoder man kan förvänta sig om det går bra vid PATCH är 200 eller 204.
DELETE
DELETE tar bort befintliga objekt till exempel så skulle DELETE: /airplanes/4567/seats/35 ta bort säte 35 från flygplanet med id 4567. DELETE: /airplanes/4567/seats skulle ta bort alla säten från flygplanet 4567. Statuskoder man kan använda om det går bra är 200, 202 eller 204,
HEAD
HEAD fungerar ungefär som en GET bara att den inte returnerar någon body. Detta kan till exempel användas om man vill veta om en resurs finns innan man ska uppdatera den.
OPTIONS
OPTIONS används för att ta reda på vilka kommunikationsval man har. Den returnerar till exempel vika http verb som kan användas på en resurs, vilka headers som är godkända mm. Detta används ofta när javascript körs i browsern och anropar apier som finns på en annan server för att kontrollera Cross Origin Resource Sharing (CORS)