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