RESTful

 API  Design  –  OCTO  Quick  Reference  Card     AUDIENCE  :  API  DESIGNERS  –  API  DEVELOPERS  
 
General  concepts   Medium  grained  resources   { "id":"007", !
"firstname":"James",!
  You  should  use  medium  grained,  not  fine  nor  coarse.   "name":"Bond",!
KISS   Resources  shouldn’t  be  nested  more  than  two  level  deep  :! "address":{!
Anyone  should  be  able  to  use  your  API  without  having  to  refer  to  the  documentaTon.   GET /users/007! "street":"H.Ferry Rd.",!
"country":{"name":"London"}!
• Use  standard,  concrete  and  shared  terms,  not  your  specific  business  terms  or  acronyms.     }!
• Never  allow  applicaTon  developers  to  do  things  more  than  one  way.     }!
• Design  your  API  for  your  clients  (ApplicaTon  developers),  not  for  your  data.   You  may  consider  the  following  five  subdomains  

• Target  major  uses  cases  first,  deal  with  excepTons  later.   • ProducTon  -­‐  https://api.fakecompany.com  
GET /orders, GET /users, GET /products, ...! • Tests  -­‐  https://api.sandbox.fakecompany.com  
! • Developer  portal  -­‐  https://developers.fakecompany.com!
CURL   • ProducTon  -­‐  https://oauth2.fakecompany.com
You  should  use  CURL  to  share  examples,  which  can  be  easily  copy/paste.   • Tests - https://oauth2.sandbox.fakecompany.com
CURL –X POST \!  
-H "Accept: application/json" \ Security  :  OAuth2  &  HTTPS  
-H "Authorization: Bearer at-80003004-19a8-46a2-908e-33d4057128e7" \ ! You  should  use  OAuth2  to  manage  AuthorizaTon.  
-d '{"state":"running"}' \ ! • OAuth2  matches  99%  of  requirements  and  client  typologies,  don't  reinvent  the  wheel,  you'll  fail.  
https://api.fakecompany.com/v1/users/007/orders?client_id=API_KEY_003 ! You  should  use  HTTPS  for  every  API/OAuth2  requests.  
!  
   
URLs   CRUD-­‐like  operaGons  :  Use  HTTP  verbs  for  CRUD  operaTons  (Create/Read/Update/Delete).  
 
  HTTP  Verb   CollecGon  :  /orders   Instance  :  /orders/{id}  
 
Nouns  
  GET   Read  a  list  orders.  200  OK.   Read  the  detail  of  a  single  order.  200  OK.  
You  should  use  nouns,  not  verbs  (vs  SOAP-­‐RPC).  
GET /orders not /getAllOrders!   POST   Create  a  new  order.  201  Created.   -­‐  
!  
  PUT   Full  Update  :  200  OK./  Create  a  specific  order  :  
Plurals   -­‐  
201  Created.  
You  should  use  plural  nouns  not  singular  nouns  to  manage  two  different  types  of  resources  :      
• CollecTon  resource  :  /users     PATCH   -­‐   ParTal  Update.  200  OK.  
 
• Instance  resource  :  /users/007    
DELETE   -­‐   Delete  order.  204  OK.  
 
You  should  remain  consistent.  
GET /users/007 not GET /user/007! POST  is  used  to  Create  an  instance  of  a  collecTon.  The  ID  isn’t  provided,  and  the  new  resource  locaTon  is  
! returned  in  the  “LocaTon”  Header.  
Consistent  case   POST /orders {"state":"running", "id_user":"007"}!
201 Created !
You  may  choose  between  snake_case  or  camelCase  for  aWributes  and  parameters,    but  you  should  
Location: https://api.fakecompany.com/orders/1234!
remain  consistent.  
GET /orders?id_user=007 ! or    GET /orders?idUser=007!
POST/orders {"id_user":"007"} ! or POST/orders {"idUser":"007"}! But  remember  that,  if  the  ID  is  specified  by  the  client,  PUT  is  used  for  Create.  
PUT /orders/1234!
 
201 Created !
If  you  have  to  use  more  than  one  word  in  URL,  you  should    use  spinal-­‐case  (some  servers  ignore  case).   !
POST /specific-orders!
PUT  is  used  for  Update  to  perform  a  full  replacement.  
  PUT /orders/1234 {"state":"paid", "id_user":"007"}!
Versioning   200 Ok!
You  should  make  versioning  mandatory  in  the  URL  at  the  highest  scope  (major  versions).    
You  may  support  at  most  two  versions  at  the  same  Tme  (NaTve  apps  need  a  longer  cycle).   PATCH  is  commonly  used  for  parTal  Update.  
GET /v1/orders! PATCH /orders/1234 {"state":"paid"}!
! 200 Ok!
Hierarchical  structure    
You  should  leverage  the  hierarchical  nature  of  the  URL  to  imply  structure  (aggregaTon  or  composiTon).     GET  is  used  to  Read  a  collecTon.                                GET  is  used  to  Read  an  instance.  
Ex  :  an  order  contains  products.   GET /orders ! ! GET /orders/1234!
GET /orders/1234/products/1! 200 Ok ! ! 200 Ok!
! [{"id":"1234", "state":"paid"} {"id":"1234", "state":"paid"}!
{"id":"5678", "state":"running"}]!
!
©2014  OCTO  Technology   www.octo.com  
!
Page  1  
 RESTful  API  Design  –  OCTO  Quick  Reference  Card     AUDIENCE  :  API  DESIGNERS  –  API  DEVELOPERS  

Query  strings   Other  key  concepts    

   
Search   Content  negoGaGon  
You  may  use  the  “Google  way”  to  perform  a  global  search  on  mulTple  resources.   Content  negoTaTon  is  managed  only  in  a  pure  RESTful  way.  The  client  asks  for  the  requierd  content,  in  
GET /search?q=running+paid! the  Accept  Header,  in  order  of  preference.  Default  format    is  JSON.    

Accept: application/json, text/plain not /orders.json!
Filters   !
You  should  use  ‘?’  to  filter  resources   I18N  
GET /orders?state=payed&id_user=007! Use  ISO  8601  standard  for  Date/Time/Timestamp  :  1978-05-10T06:06:06+00:00  or  1978-05-10!
or  (mulTple  URIs  may  refer  to  the  same  resource)   Add  support  for  different  Languages.      
GET /users/007/orders?state=paied! Accept-Language: fr-ca, fr-fr not ?language=fr!
! !
PaginaGon   Cross-­‐origin  requests  
You  may  use  a  range  query  parameter.  PaginaTon  is  mandatory  :  a  default  paginaTon  has  to  be   Use  CORS  standard  to  support  REST  API  requests  from  browsers  (js  SPA…).  
defined,  for  example  :  range=0-­‐25.     But  if  you  plane  to  support  Internet  Explorer  7/8  or  9,  you  shall  consider  specifics  endpoints  to  add  a  
The  response  should  contains  the  following  headers  :  Link,  Content-­‐Range,  Accept-­‐Range.   Jsonp  support.  
Note  that  paginaTon  may  cause  some  unexpected  behavior  if  many  resources  are  added.   • All  requests  will  be  sent  with  a  GET  method!  
/orders?range=48-55! • Content  negoTaTon  cannot  be  handled  with  Accept  Header  in  Jsonp.  
206 Partial Content! • Payload  cannot  be  used  to  send  data.  
Content-Range: 48-55/971! !
Accept-Range: order 10! POST /orders and /orders.jsonp?method=POST&callback=foo!
Link : <https://api.fakecompany.com/v1/orders?range=0-7>; rel="first", ! GET /orders and /orders.jsonp?callback=foo!
<https://api.fakecompany.com/v1/orders?range=40-47>; rel="prev", ! GET /orders/1234 and /orders/1234.jsonp?callback=foo!
<https://api.fakecompany.com/v1/orders?range=56-64>; rel="next", ! PUT /orders/1234 and /orders/1234.jsonp?method=PUT&callback=foo!
<https://api.fakecompany.com/v1/orders?range=968-975>; rel="last"!  
! Warning  :  a  web  crawler  could  easily  damage  your  applicaTon  with  a  method  parameter.  Make  sure  that  
ParGal  responses   an  OAuth2  access_token  is  required,  and  an  OAuth2  client_id  as  well.  
You  should  use  parTal  responses  so  developers  can  select    informaTon  needed  and  opTmize  bandwidth    
(essenTal  for  mobile  development).   HATEOAS  
GET /users/007?fields=firstname,name,address(street)! Your  API  should  propose  Hypermedia  links  in  order  to  be  completely  discoverable.  But  keep  in  mind  that  
200 OK!
{ "id":"007", !
a  majority  of  users  wont  probably  use  those  hyperlinks  (for  now),  and  will  read  the  API  documentaTon  
"firstname":"James",! and  copy/paste  call  examples.  
"name":"Bond",! So,  each  call  to  the  API  should  return  in  the  Link  Header  every  possible  state  of  the  applicaTon  from  the  
address:{"street":"Horsen Ferry Road"}! current  state,  plus  self.    
}! You  may  use  RFC5988  Link  notaTon  to  implement  HATEOAS  :  
GET /users/007!
Sort   < 200 Ok!
Use  ?sort  =atribute1,atributeN  to  sort  resources.  By  default  resources  are  sorted  in  ascending  order.   < { "id":"007", "firstname":"James",...}!
Use  ?desc=atribute1,atributeN  to  sort  resources  in  descending  order   < Link : <https://api.fakecompany.com/v1/users>; rel="self"; method:"GET",!
GET /restaurants?sort=rating,reviews,name;desc=rate,reviews! <https://api.fakecompany.com/v1/addresses/42>; rel="addresses"; method:"GET",!
! <https://api.fakecompany.com/v1/orders/1234>; rel="orders"; method:"GET"!
URL  reserved  words  :  first,  last,  count  
Use  /first  to  get  the  1st  element    Use  /last  to  retrieve  the  latest  resource  of  a  collecTon   “Non Resources” scenarios
GET /orders/first
! !GET /orders/last! In a few use cases we have to consider operations or services rather than resources.
200 OK ! !200 OK! You may use a POST request with a verb at the end of the URI
{"id":"1234", "state":"paid"} !{"id":"5678", "state":"running"} ! POST /emails/42/send!
POST /calculator/sum [1,2,3,5,8,13,21]!
Use  /count  to  get  the  current  size  of  a  collecTon   POST /convert?from=EUR&to=USD&amount=42!
!
GET /orders/count !!
!
200 OK !
!
{"2"} !
 

©2014  OCTO  Technology   www.octo.com   Page  2  

 RESTful  API  Design  –  OCTO  Quick  Reference  Card     AUDIENCE  :  API  DESIGNERS  –  API  DEVELOPERS  

HTTP  Status  codes  

 
You  must  use  adequate  HTTP  status  code.    
You  may  use  OAuth2  standard  notaTon    :  hWp://tools.ieu.org/html/rfc6749#page-­‐45  
Keep  it  simple  :  you  shouldn’t  try  to  use  all  HTTP  status  code,  but  only  the  TOP  12.  

HTTP  Verb   HTTP  Status  code   DescripGon  

200  OK.   Basic  success  code.  Works  for  the  general  case.  Especially  used  on  successful  first  GET  requests,  or  PUT/PATCH  updated  content.  
201  Created.   Indicates  that  a  resource  was  created.  Typically  responding  to  PUT  and  POST  request.  
SUCCESS   202  Accepted.     Indicates  that  the  request  has  been  accepted  for  processing.  Typically  responding  to  an  asynchronous  processing  call  (for  a  beWer  UX  and  good  performances).  
204  No  Content.     The  request  succeeded  but  there’s  really  nothing  to  show.  Usually  sent  axer  a  successful  DELETE.  
206  ParTal  Content.     The  returned  resource  is  incomplete.  Typically  used  with  paginated  resources.    
General  error  for  any  request  (if  it  doesn’t  fit  in  any  other).  A  good  pracTce  will  be  to  manage  two  kind  of  errors:  request  behavior  errors,  and  applicaTon  condiTon  
errors.  
 
Request  behavior  error  example:  
GET  /users?payed=1  
<  400  Bad  Request  
400  Bad  request.   <  {"error":  "invalid_request",  "error_descripTon":  "There  is  no  ‘payed’  property  on  users."}  
 
ApplicaTon  condiTon  error  example:  
POST  /users  
{"name":  "John  Doe”}  
<  400  Bad  Request  
<  {"error":  "invalid_user",  "error_descripTon":  "A  user  must  have  an  email  adress"}!
I  don’t  know  you,  tell  me  who  you  are  and  I  will  check  your  permission.  
GET  /users/42/orders  
401  Unauthorized.     <  401  Unauthorized  
<  {"error":  "no_credenTals",  "error_descripTon":  "This  resource  is  under  permission,  you  must  be  authenTcated  with  the  right  rights  to  have  access  to  it"}!
Your  credenTals  rights  aren’t  sufficient  to  access  this  resource.  
CLIENT  ERROR   GET  /users/42/orders  
403  Forbidden.     <  403  Forbidden  
<  {"error":  "not_allowed",  "error_descripTon":  "You’re  not  allowed  to  perform  this  request"}!
The  resource  you’re  requesTng  doesn’t  exist  
GET  /users/999999  
404  Not  Found.     <  400  Not  Found  
<  {"error":  "not_found",  "error_descripTon":  "The  user  with  the  id  ‘999999’  doesn’t  exist"}!
Either  it  doesn’t  make  sense  to  call  such  a  method  on  this  resource  or  the  authenTcated  user  doesn’t  have  the  right  to  do  it.  
POST  /users/8000  
405  Method  not  allowed.     <  405  Method  Not  Allowed  
<  {"error":"method_does_not_make_sense",  "error_descripTon":"How  would  you  even  post  a  person?"}!
There’s  nothing  to  send  that  matches  the  Accept-­‐*  headers  of  the  request.  For  example,  you  requested  a  resource  in  XML  and  the  resource  is  only  available  in  JSON.  
This  also  works  for  i18n  
GET  /users  
406  Not  Acceptable.     Accept:  text/xml  
Accept-­‐Language:  fr-­‐fr  
<  406  Not  Acceptable  
<  Content-­‐Type:  applicaTon/json  
<  {"error":  "not_acceptable",  "available_languages":["us-­‐en",  "de",  "kr-­‐ko"]}!
The  request  call  is  right,  but  a  problem  is  encountered.  The  client  can’t  really  do  anything  about  that,  so  we  suggest  to  return  a  500  status  code.  
GET  /users  
SERVER  ERROR  
500  Internal  server  Error.     <  500  Internal  server  error  
  <  Content-­‐Type:  applicaTon/json  
<  {"error":"server_error",  "error_descripTon":"Oops!  Something  went  wrong...  "}  

©2014  OCTO  Technology   www.octo.com   Page  3  

 RESTful  API  Design  –  OCTO  Quick  Reference  Card     AUDIENCE  :  API  DESIGNERS  –  API  DEVELOPERS  

DISCLAMER  
This  Reference  Card  doesn’t  claim  to  be  absolutely  accurate.  The  design  concepts  
exposed  result  from  our  pervious  work  in  the  REST  area.  Please  check  out  our  blog  
hWp://blog.octo.com,  and  feel  free  to  comment/challenge  this  API  cookbook.  We  
are  really  looking  forward  to  sharing  with  you.  
 
One  more  thing  
We  encourage  you  to  be  pragmaTc,  for    the  benefit  of  your  customers…  
Applica'on  developers.  
 
Sources  
Design  BeauTful  REST  +  JSON  APIs  
>  hWp://www.slideshare.net/stormpath/rest-­‐jsonapis  
 
Web  API  Design:  Craxing  Interfaces  that  Developers  Love  
>  hWps://pages.apigee.com/web-­‐api-­‐design-­‐website-­‐h-­‐ebook-­‐registraTon.html  
 
HTTP  API  Design  Guide  
>  hWps://github.com/interagent/hWp-­‐api-­‐design  
 
RESTful  Web  APIs  
>  hWp://shop.oreilly.com/product/0636920028468.do  
 

©2014  OCTO  Technology   www.octo.com   Page  4