Scalabay - API Design Antipatterns
4 likes1,167 views
The document discusses best practices for designing APIs, focusing on REST architecture and key patterns to avoid common mistakes. It covers various topics including request and response patterns, the use of HTTP methods, and the importance of proper resource identification and metadata. Additionally, it highlights the significance of maintaining statelessness and proper error handling in API interactions.
Scalabay - API Design Antipatterns
- 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
- 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
- 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
- 31. Over-‐using Query Strings @lobster1234
- 32. /pets?name=scruffy vs. /pets/name/scruffy @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
- 44. Using Query Strings to overload verbs @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
- 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
- 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