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

Transcript

1. API  An&pa)erns   …iden&fying,  and  avoiding  them     Manish Pandit @lobster1234
2.   Manish  Pandit   @lobster1234   mpandit  at  neAlix  dot  com     linkedin.com/in/mpandit   slideshare.net/lobster1234   @lobster1234
3. APIs       A  means  for  soGware  to  interact  with  other   soGware.   @lobster1234
4.     @lobster1234
5. @lobster1234 Image  Credit:  h)p://en.wikipedia.org/wiki/Internet_of_Things  
6. @lobster1234
7. REST  API   REST  is  not  a  standard,  but  an  architecture     @lobster1234
8. 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
9. @lobster1234
10. REST  API     Noun  è  Resource,  or  the  En&ty     Verb  è  Ac&on   +   Iden.fier     @lobster1234
11. Image:  h)p://www.educa&on.com/study-­‐help/ar&cle/nouns/     @lobster1234
12. Protocol       May  or  may  not  be  standard   @lobster1234
13. Protocol         May  or  may  not  be  standard   Indicates  an  agreement  between  the  par&es       @lobster1234
14. @lobster1234
15. Payload         Format  (XML,  JSON,  Custom  Text,  Binary..)     Transport  (HTTP,  Binary  over  sockets,  FTP..)   @lobster1234
16.     @lobster1234
17.     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
18. Every  request  deserves  a  response.   @lobster1234
19. Headers  describe  the  response   @lobster1234
20. Headers  describe  the  response     Status  Code  indicates  the  success/failure   @lobster1234
21.   Headers  describe  the  response     Status  Code  indicates  the  success/failure     Body  contains  the  actual  payload   @lobster1234
22.     Tell  the  server  what  to  do  via  ac.ons   @lobster1234
23.     Ac&ons  are  HTTP  methods,  which  map  nicely  to   (most  of)  the  business  interac&ons   @lobster1234
24.   Create  –  POST   Read  –  GET   Update  –  PUT  (or  PATCH)   Delete  -­‐  DELETE     HEAD,  OPTIONS,  TRACE,  CONNECT   @lobster1234
25. Pa)erns   @lobster1234
26. Pa)erns   Pa)erns  are  re-­‐usable  solu&ons  to  commonly   occurring  problems.   @lobster1234
27. Common  Scenarios       Gebng  data  from  the  server       @lobster1234
28. Common  Scenarios       Gebng  data  from  the  server     Sending  data  to  the  server     @lobster1234
29. 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
30.     Request  An&pa)erns   @lobster1234
31.     Over-­‐using  Query  Strings   @lobster1234
32.     /pets?name=scruffy   vs.   /pets/name/scruffy   @lobster1234
33.     /pets?name=scruffy&zip=94568   vs.   /pets/name/scruffy/loca&on/zip/94568   @lobster1234
34.       Avoid  query  strings  for  resource  iden&fica&on   But  use  them  for  request  metadata  *       *Except  for  search   @lobster1234
35.     Pagina&on   Filtering   Sor&ng   ..   @lobster1234
36. @lobster1234
37. Query  Strings     h)p://some.api.com/movies? start=0&count=10&sortBy=name&fields=name, cast,releaseDate   @lobster1234
38.     Allowing  clients  to  scrape  the  data  via  your  APIs   @lobster1234
39. @lobster1234
40.     Think  batch  jobs  reques&ng  the  catalog  nightly!   @lobster1234
41.     Request  metadata  to  the  rescue?   @lobster1234
42.       ….how  about  a  ?since=1d     …or  ?since=UTC   @lobster1234
43.     Method  An&pa)erns   @lobster1234
44.     Using  Query  Strings  to  overload  verbs   @lobster1234
45.       /pets?perform=update&name=scruffy&id=24   @lobster1234
46.       Use  the  appropriate  HTTP  Method  to  represent   your  ac&on     @lobster1234
47.     Using  POST  for  all  writes   @lobster1234
48.       GET  to  retrieve,  or  search   POST  to  create,  or  upsert   PUT  to  update  (or  be)er  yet,  PATCH)   DELETE  to  delete   @lobster1234
49.     Using  HTTP  PUT  or  POST  to  set  a  value  to  null   @lobster1234
50. Updates  vs.  Deletes     Everything  works  when  there  is  data,  but  what   when  there  is  no  data..?   @lobster1234
51.       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
52.       DELETE  /pets/<id>/collartag       @lobster1234
53.     Response  An&pa)erns   @lobster1234
54.     Always  returning  HTTP  200   @lobster1234
55. @lobster1234
56. HTTP  200  OK     {  “success”  :  false  }   @lobster1234
57. HTTP  200  OK     {  “error”  :  ”Person  jdoe  not  found”  }   @lobster1234
58.     2xx  for  success   3xx  for  redirects/caching   4xx  for  request/client  errors   5xx  for  server  errors   @lobster1234
59. 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
60.   Always  returning  a  401  for  auth  failures      
61. @lobster1234
62. Auth         Use  HTTP  401  Unauthorized  to  indicate  that  the   client  needs  to  authen&cate   @lobster1234
63. Auth         Use  HTTP  403  Forbidden  to  indicate  that  the   client’s  creden&als  do  not  allow  access  to  the   requested  resource   @lobster1234
64. 401  vs  403       401  =  Come  back  with  a  key     403  =  Your  key  does  not  work  for  this  lock.   @lobster1234
65.   Processing  requests  synchronously,  even  &me   intensive  ones     @lobster1234
66.       Async  the  opera&on,  and  return     HTTP  202  –  Accepted       @lobster1234
67. @lobster1234
68.   Async  opera&on’s  response  should  help  the   caller.     {“statusUrl”:  <some  URL>}   @lobster1234
69.     Organiza&onal  An&pa)erns   @lobster1234
70.     Not  differen&a&ng  between  en..es  and   instances     @lobster1234
71.     /pets?type=dog&name=big     vs     /pets/dogs/name/big   @lobster1234
72.       Namespace  your  resources  in  a  collec&on   Use  paths  and  iden&fiers  to  traverse       @lobster1234
73.     Using  id  in  the  resource  iden&fica&on  path     @lobster1234
74.   /pets/id/1234     vs     /pets/1234   @lobster1234
75.       Use  all  other  a)ributes  in  the  path,  except  the   id.     id  is  implied   @lobster1234
76.   @lobster1234 Resources  in  an  island  
77. @lobster1234
78.   Every  en&ty  or  a  resource  is  &ed  to  others.     @lobster1234
79.   Every  en&ty  or  a  resource  is  &ed  to  others.     And  you’re  stuck  guessing  the  connec&ons!   @lobster1234
80.   @lobster1234 We’ll  just  return  the  IDs!  
81.   HATEOAS   (or  something  similar)   @lobster1234
82.   Read  code  to  figure  out  the  resources  and   a)ributes.             @lobster1234
83. @lobster1234
84.       Use  Meta  pages  for  resource  descrip&on   /resource/meta   /collec&on/meta   @lobster1234
85.   APIs  are  not  discoverable             @lobster1234
86.       Consider  a  documenta&on  generator  like   Swagger,  IODocs   @lobster1234
87.   Relying  on  cookies  for  authen&ca&on   @lobster1234
88. @lobster1234
89.   Accept  cookies  as  a  fallback,  but  prefer  a  query   parameter  or  HTTP  request  header.     @lobster1234
90.   Storing  state  on  the  server  nodes   @lobster1234
91.     Stateless  ==  Simple   @lobster1234
92.     Requests  either  modify  the  state  of  a  resource,  or  read   it.     All  requests  to  the  cluster  see  the  same  state  of  the   resource     @lobster1234
93.       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
94. Versioning   Using  301s  to  redirect/re&re  APIs     Caching   Using  HTTP  headers  correctly   Caching  response  bodies   @lobster1234
95. @lobster1234 Fin