Scalabay - API Design Antipatterns
4 likes1,165 views
Slides from my talk on API Design Patterns at ScalaBay Meetup at Netflix on 09/09/2014. http://www.meetup.com/Scala-Bay/events/195982742/
Ad
More Related Content
What's hot (18)
Viewers also liked (20)
Ad
Similar to Scalabay - API Design Antipatterns (20)
Ad
More from Manish Pandit (20)
Recently uploaded (20)
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