Upgrade to Pro — share decks privately, control downloads, hide ads and more …

ScalaBay - API Design Antipatterns

Manish Pandit
September 09, 2014

ScalaBay - API Design Antipatterns

Slides from my talk on API Design Antipatterns for ScalaBay Meetup at Netflix on 09/09/2014.

Video here - https://www.youtube.com/watch?v=MdKg7NeHrnc

Manish Pandit

September 09, 2014
Tweet

More Decks by Manish Pandit

Other Decks in Technology

Transcript

  1.   Manish  Pandit   @lobster1234   mpandit  at  neAlix  dot

     com     linkedin.com/in/mpandit   slideshare.net/lobster1234   @lobster1234
  2. APIs       A  means  for  soGware  to  interact

     with  other   soGware.   @lobster1234
  3. REST  API   REST  is  not  a  standard,  but  an

     architecture,   which  uses  HTTP  as  a  model  for  all  interac.ons.     If  HTTP  is  a  standard,  REST  is  a  conven&on.   @lobster1234
  4. REST  API     Noun  è  Resource,  or  the  En&ty

        Verb  è  Ac&on   +   Iden.fier     @lobster1234
  5. Protocol         May  or  may  not  be

     standard   Indicates  an  agreement  between  the  par&es       @lobster1234
  6. Payload         Format  (XML,  JSON,  Custom  Text,

     Binary..)     Transport  (HTTP,  Binary  over  sockets,  FTP..)   @lobster1234
  7.     h)p://www.neAlix.com/header/neAlix_logo.gif     Or,  reques.ng  a  resource  from

     the  server  by   giving  its  path  using  a  protocol.   @lobster1234
  8.   Headers  describe  the  response     Status  Code  indicates

     the  success/failure     Body  contains  the  actual  payload   @lobster1234
  9.     Ac&ons  are  HTTP  methods,  which  map  nicely  to

      (most  of)  the  business  interac&ons   @lobster1234
  10.   Create  –  POST   Read  –  GET   Update

     –  PUT  (or  PATCH)   Delete  -­‐  DELETE     HEAD,  OPTIONS,  TRACE,  CONNECT   @lobster1234
  11. Common  Scenarios       Gebng  data  from  the  server

        Sending  data  to  the  server     @lobster1234
  12. An&pa)erns         An&pa)erns  are  re-­‐usable  solu&ons  to

       commonly   occurring  problems,  that  look  great  on  the  surface,  but   really  aren’t.     @lobster1234
  13.       Avoid  query  strings  for  resource  iden&fica&on  

    But  use  them  for  request  metadata  *       *Except  for  search   @lobster1234
  14.       GET  to  retrieve,  or  search   POST

     to  create,  or  upsert   PUT  to  update  (or  be)er  yet,  PATCH)   DELETE  to  delete   @lobster1234
  15.     Using  HTTP  PUT  or  POST  to  set  a

     value  to  null   @lobster1234
  16. Updates  vs.  Deletes     Everything  works  when  there  is

     data,  but  what   when  there  is  no  data..?   @lobster1234
  17.       Use  HTTP  DELETE  to  set  a  value

     to  null     Remember,  we  have  a  path  to  not  just  the  resource,  but  also  it’s   a)ributes   @lobster1234
  18.     2xx  for  success   3xx  for  redirects/caching  

    4xx  for  request/client  errors   5xx  for  server  errors   @lobster1234
  19. Some  Useful  (and  not  so  common)  Codes     Return

     aGer  a  delete  -­‐  204   Failed  database  constraint  -­‐  409   Method  not  supported  -­‐  405   Trying  to  ask  for  too  much  data  -­‐  413   Valida&on  Failure  -­‐  418   @lobster1234
  20. Auth         Use  HTTP  401  Unauthorized  to

     indicate  that  the   client  needs  to  authen&cate   @lobster1234
  21. Auth         Use  HTTP  403  Forbidden  to

     indicate  that  the   client’s  creden&als  do  not  allow  access  to  the   requested  resource   @lobster1234
  22. 401  vs  403       401  =  Come  back

     with  a  key     403  =  Your  key  does  not  work  for  this  lock.   @lobster1234
  23.       Async  the  opera&on,  and  return    

    HTTP  202  –  Accepted       @lobster1234
  24.   Async  opera&on’s  response  should  help  the   caller.  

      {“statusUrl”:  <some  URL>}   @lobster1234
  25.       Namespace  your  resources  in  a  collec&on  

    Use  paths  and  iden&fiers  to  traverse       @lobster1234
  26.       Use  all  other  a)ributes  in  the  path,

     except  the   id.     id  is  implied   @lobster1234
  27.   Every  en&ty  or  a  resource  is  &ed  to  others.

        And  you’re  stuck  guessing  the  connec&ons!   @lobster1234
  28.   Read  code  to  figure  out  the  resources  and  

    a)ributes.             @lobster1234
  29.       Use  Meta  pages  for  resource  descrip&on  

    /resource/meta   /collec&on/meta   @lobster1234
  30.   Accept  cookies  as  a  fallback,  but  prefer  a  query

      parameter  or  HTTP  request  header.     @lobster1234
  31.     Requests  either  modify  the  state  of  a  resource,

     or  read   it.     All  requests  to  the  cluster  see  the  same  state  of  the   resource     @lobster1234
  32.       Avoid  state  as  much  as  possible.  

    Maintain  the  state  in  the  database.   If  you  need  to  store  transient  state  on  the  server,  it’s  a   code  (or  architecture)  smell.   @lobster1234
  33. Versioning   Using  301s  to  redirect/re&re  APIs     Caching

      Using  HTTP  headers  correctly   Caching  response  bodies   @lobster1234