octo restful api design blue refcard

consistent case example

GET /v1/orders?id_user=007
OR
GET /v1/orders?idUser=007
---------------------------------
POST /v1/orders {"id_user":"007"}
OR
POST /v1/orders {"idUser":"007"}

curl example

CURL –X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer at-80003004-19a8-46a2-908e-33d4057128e7" \
  -d ‘{"state":"running"}’ \
  https://api.fakecompany.com/v1/users/007/orders?client_id=API_KEY_003 

granularity example

GET /v1/users/007
{ "id": "007",
  "first_name": "James",
  "name": "Bond",
  "address": {
    "street": "Horsen Ferry Road",
    "city": { "name":"London" }
  }
}

hateos example

GET /users/007
200 Ok
Link : <https://api.fakecompany.com/v1/users>; rel="self"; method:"GET",
       <https://api.fakecompany.com/v1/addresses/42>; rel="addresses"; method:"GET",
       <https://api.fakecompany.com/v1/orders/1234>; rel="orders"; method:"GET"

{ "id":"007", "firstname":"Mario",...}

jsonp example

POST /v1/orders      and GET /v1/orders.jsonp?method=POST&callback=foo
GET  /v1/orders      and GET /v1/orders.jsonp?callback=foo
GET  /v1/orders/1234 and GET /v1/orders/1234.jsonp?callback=foo
PUT  /v1/orders/1234 and GET /v1/orders/1234.jsonp?method=PUT&callback=foo

non resource scenario

POST /v1/emails/42/send
POST /v1/calculator/sum [1,2,3,5,8,13,21]
POST /v1/convert?from=EUR&to=USD&amount=42

pagination example

GET /v1/orders?range=48-55

206 Partial Content
Content-Range: 48-55/971
Accept-Range: order 10
Link :  <https://api.fakecompany.com/v1/orders?range=0-7>; rel="first",
        <https://api.fakecompany.com/v1/orders?range=40-47>; rel="prev",
        <https://api.fakecompany.com/v1/orders?range=56-64>; rel="next",
        <https://api.fakecompany.com/v1/orders?range=968-975>; rel="last"

partial response example

GET /v1/users/007?fields=firstname,name,address(street)

200 OK
{ "id":"007",
  "firstname":"James",
  "name":"Bond",
  "address":{"street":"Horsen Ferry Road"}
}

reserved words examples

GET /v1/orders/first

200 OK
{"id":"1234", "state":"paid"}
----------------------------------
GET /v1/orders/last

200 OK
{"id":"5678", "state":"running"} 
----------------------------------
GET /v1/orders/count

200 OK
2