API Antipatterns : APICon SF

My talk at APICon San Francisco on API Antipatterns.

APIs have become a part of the product ecosystem - and help the businesses by extending their developer base, and offering seamless integration with other services or products. Sometimes, the APIs themselves are the product. However, with so many APIs around, patterns emerge. Patterns are repeatable, reusable solutions to commonly occurring problems. Where there are patterns, there are also antipatterns. While APIs are not a new paradigm - there are no set standards or specifications formed by a committees or governing bodies for APIs. On top of this, the APIs are often built at various stages of the product, and have a good chance of being disjoint as more are added. In this talk Netflix engineers will discuss various antipatterns that creep into the API design and implementation, and how to identify and avoid them. They will also share their experiences with building APIs. While the antipatterns do not pose as big a functional challenge, they can and do impact integration efforts, scalability and performance among other things. After this session, you should be able to get familiar with the best practices around solving the most common patterns, and make your engineers and API consumers happy! -

Transcript

1. API  An&pa)erns   …iden&fying,  and  avoiding  them   Manish Pandit mpandit@netflix.com lobster1234
2. APIs      
3. APIs       A  means  for  so+ware  to  interact  with  other   so+ware.  
4. Protocol  
5. Protocol   – May  or  may  not  be  standard  
6. Protocol   – May  or  may  not  be  standard   – Indicates  an  agreement  between  the  par&es  
7. Payload  
8. Payload   Data  Format     •  XML   •  JSON   •  Custom  Text   •  Binary…    
9. Payload         Transport  mechanism     •  HTTP     •  SMTP   •  Custom  Text-­‐based   •  Raw  sockets  
10. HTTP  Request       h)p  
11. HTTP  Request       h)p://www.neSlix.com  
12. HTTP  Request       h)p://www.neSlix.com/header  
13. HTTP  Request       h)p://www.neSlix.com/header/neSlix_logo.gif    
14. HTTP  Request       h)p://www.neSlix.com/header/neSlix_logo.gif     Or,  geUng  a  resource  from  the  server  by  giving   its  loca&on.  
15. Every  request  has  a  response.  
16. HTTP  Response   – Headers   •  Describing  the  response  
17. HTTP  Response   – Headers   •  Describing  the  response   – Status  Code   •  Indica&ng  the  success/failure  
18. HTTP  Response   – Headers   •  Describing  the  response   – Status  Code   •  Indica&ng  the  success/failure   – Body   •  The  data  we  asked  for  
19. REST  API   REST  is  not  a  standard,  but  an  architecture    
20. REST  API   REST  is  not  a  standard,  but  an  architecture,   which  uses  HTTP  as  a  model  for  all  interac/ons.  
21. REST  API   •  Noun  è  Resource,  or  the  En&ty   •  Verb  è  Ac&on  
22. Pa)erns  
23. Pa)erns   Pa3erns  are  re-­‐usable  solu8ons  to  commonly  occurring  problems.  
24. Pa)erns   They  are  iden8fied  by  humans  who  write  code  –  the  API  as  well  as  the  client.  
25. Common  Scenarios   “GeUng  data  from  the  server”  
26. Common  Scenarios   “Sending  data  to  the  server”  
27. An&pa)erns     “An8pa3erns  are  re-­‐usable  solu8ons  to     commonly  occurring  problems…    
28. An&pa)erns     ....which  look  great  on  the  surface  but  they   really  aren’t  ”  
29. HTTP  Response  Codes   HTTP  200  OK     {  “success”  :  false  }  
30. HTTP  Response  Codes   HTTP  200  OK     {  “error”  :  ”Person  abc  not  found”  }  
31. HTTP  Response  Codes   •  There  are  more  codes  than    200  and  500   – 2xx  for  success   – 3xx  for  redirects/caching   – 4xx  for  request/client  errors   – 5xx  for  server  errors  
32.       also,  the  client  does  not  need  to  see  your  excep&on   trace…  
33. HTTP  Response  Codes   •  Return  acer  a  delete?  204   •  Failed  database  constraint?  409   •  Method  not  supported?  405   •  Trying  to  ask  for  too  much  data?  413  
34. Query  Strings   •  /pets?name=scruffy  
35. Query  Strings   •  /pets?name=scruffy   •  /pets/name/scruffy  
36. Query  Strings   •  Avoid  query  strings  for  resource  iden&fica&on  
37. Query  Strings   •  Avoid  query  strings  for  resource  iden&fica&on   •  But  use  them  for  request  metadata  
38. Query  Strings   •  Request  Metadata   – Pagina&on   – Filtering   – Sor&ng  
39. Query  Strings     h)p://some.api.com/movies? start=0&count=10&sortBy=name&fields=name, cast,releaseDate  
40. Methods   •  Do  not  use  GET  for  all  reads   – HEAD  to  get  headers  (mostly  used  for  caching)   – OPTIONS   •  Do  not  use  POST  for  all  writes   – POST  to  create,  or  upsert   – PUT  to  update   – DELETE  to  delete  
41. Resources  vs.  Collec&ons     A  collec&on  holds  similar  resources   – movies   – accounts   – persons  
42. Resources  vs.  Collec&on     A  path  should  iden&fy  a  resource  (or  resources)   in  a  collec&on  of  said  resources  
43. Resources  vs.  Collec&ons   •  /movies/name/{name}   •  /users/1234   •  /devices/type/bdplayers  
44. Resources  vs.  Collec&on     Always  specify  a  qualifier  in  the  path  when   accessing  resource(s)  in  a  collec&on  
45. Resources  vs  Collec&on       …except  when  accessing  via  the  primary  ID  
46. Resources  vs  Collec&on     Always  think  about  the  path  to  the  resource.     /<collec&on>/<resource  iden&fier>/value     And  manipulate  it  with  the  verbs  
47. Resources       Also,  the  proper&es  of  the  resource  can  also  be   a  part  of  the  path.     /movies/ra&ng/G  
48. Authen&ca&on   •  401  Unauthorized  
49. Authen&ca&on   •  403  Forbidden  
50. Authen&ca&on   •  Use  HTTP  401  to  indicate  that  the  client  needs   to  authen&cate  
51. Authen&ca&on   •  Use  HTTP  401  to  indicate  that  the  client  needs   to  authen&cate   •  Use  HTTP  403  to  indicate  that  the  creden&als   the  client  holds  do  not  allow  access  to  the  said   resource(s).  
52. 401  vs  403       401  =  Come  back  with  a  key     403  =  Your  key  does  not  work  for  this  lock.  
53. Resources  in  an  Island       Every  en&ty  or  a  resource  is  &ed  to  others.  
54. Resources  in  an  Island       When  you’re  stuck  guessing  the  connec&ons  of   a  resource.  
55. Resources  in  an  Island       HATEOAS  
56. Resources  in  an  Island       HATEOAS   (or  something  similar)  
57. Resource  Discovery   Always  have  your  resources  discoverable   ..via  code  
58. Resource  Discovery     So  we  talked  a  lot  about  discoverability  and   islands..  
59. Resource  Discovery     But  where  do  we  start?  
60. Resource  Discovery   Meta  pages  for  resources     /<collec&on>/meta   Or   </resource>/meta  
61. Async  Opera&ons       For  when  synchronous  calls  just  will  not  work  L  
62. Async  Opera&ons     HTTP  202  –  Accepted     But…what  about  the  response?    
63. Async  Opera&ons     Response  should  help  the  caller..remember?     {“statusUrl”:  <some  URL>}  
64. Updates  vs.  Deletes     Everything  works  when  there  is  data..but  what   when  there  is  no  data..?  
65. Updates  vs.  Deletes       HTTP  PUT  to  set  a  value  to  null?  
66. Updates  vs.  Deletes       HTTP  DELETE  to  set  a  value  to  null?     (Remember,  we  have  a  path  to  not  just  the   resource..)  
67. Updates  vs.  Deletes       DELETE  /movies/<id>/ra&ng      
68. Data  feeds       Whats  an  API  that  does  not  syndicate..  
69. Data  feeds       Think  nasty  batch  jobs  sucking  the  catalog   nightly!  
70. Data  feeds   Request  metadata  to  the  rescue?  
71. Data  feeds   Request  metadata  to  the  rescue?     ….how  about  a  ?since=1d     …or  ?since=UTC  
72. State       They  said  REST  is  stateless…but  is  it?  
73. State       Stateless  ==  Simple  
74. State     •  State  sits  only  on  the  server   •  Requests  either  change  the  state,  or  get  it.   •  All  requests  see  the  same  state  of  the   resource    
75. State         But  what  about  cookies?  
76. State   Avoid  cookies!   •  Use  tokens  instead.  Let  the  client  figure  out  to   store  it  as  a  cookie  for  convinience.   •  Accept  cookies  as  a  fallback,  but  prefer  a   query  parameter  or  HTTP  request  header.    
77. More  topics..     •  Versioning   – Using  301s  to  redirect/re&re  APIs   •  Caching   – Using  HTTP  headers  correctly   – Caching  response  bodies  
78. RFC  2616  
79. Ques&ons