Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Silicon Valley 2014 - API Antipatterns

1,751 views

Published on

My talk at Silicon Valley Code Camp 2014 on API Antipatterns.

Published in: Technology
  • Be the first to comment

Silicon Valley 2014 - API Antipatterns

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

×