5 Anti-Patterns in API Design
This talks elaborates on the Client-Server tenet of REST which focuses on separation of concerns between the client and the server. In the first third of the talk, I will talk about what the ideal client and servers are and examples of how their responsibilities. I will touch on how the word Server has lost its meaning of “serving” and the client has been overshadowed by the focus to the API. I will also compare the API to a restaurant and how its menu is the API’s REST resources.In the rest of the talk, I look at some important anti-patterns commonly seen in the industry (each with at least one example) 1. Chauvinist Server: designing the API from server’s perspective failing to hide its complexity behind its API (API designed from the server’s perspective). 2. Demanding client: client enforcing its special need onto the signature of the API (certain client’s limitation becomes server’s default behaviour). 3. Transparent Server: server exposing its internal implementation to its clients (server’s underlying or private domain bleeds into the public API). 4. Presumptuous Client: The client assuming the role of a server and engage in taking responsibilities that cannot guarantee. 5. Assuming Server: Server that assumes the responsibility of tailoring the response based on what it assumes client is (e.g. browser sniffing).
Recommended
Recommended
More Related Content
Viewers also liked
Viewers also liked (11)
Similar to 5 Anti-Patterns in API Design
Similar to 5 Anti-Patterns in API Design (20)
More from Ali Kheyrollahi
More from Ali Kheyrollahi (14)
Recently uploaded
Recently uploaded (20)
5 Anti-Patterns in API Design
- 1. API DESIGN 5 Anti-Patterns in Ali @aliostad Kheyrollahi
- 6. REST Caching
- 7. @aliostad Resources and representations REST Uniform Interface S e l f - d e s c r i p t i v e messages Hypermedia
- 11. @aliostad CSDS Client-Server Domain Separation “ Client and server must define and live within their own bounded context ”
- 12. @aliostad CSDS Client-Server Domain Separation S e r v e r Server - Not just a thin shell around a d a t a b a s e
- 13. @aliostad CSDS Client-Server Domain Separation S e r v e r
- 14. @aliostad CSDS Client-Server Domain Separation C l i e n t Can be a server itself1 2 Uses services of server(s) to bring value to end-user (directly or indirectly) 3 Free to take dependency on of Server’s public domain (URI, exchange domain) Normally keeps state but does not master it1
- 16. @aliostad
- 18. @aliostad “designing the API from server's perspective” Anti-Pattern Chauvinist Server Server pushes its thinking and process to the client resulting in the client becoming a subordinate
- 19. @aliostad Anti-Pattern Chauvinist Server E x a m p l e Always for a customer1 2 Only for customers currently shopping 3 Get expired after inactivity A couple of tables or a document database 4 Max one basket per customer
- 20. @aliostad Anti-Pattern Chauvinist Server E x a m p l e POST /baskets?cid=908 201 Created Location: /basket/123435455456 POST /baskets/123435455456 {...}200 OK x
- 21. @aliostad Anti-Pattern Chauvinist Server E x a m p l e POST customer/me/basket {…} 200 OK ✓
- 23. @aliostad “server exposes its internal implementation to its clients” Anti-Pattern Transparent Server server's private domain or the domain of its underlying dependencies bleeds into its public API
- 24. @aliostad Anti-Pattern Transparent Server GET /foo/bar 200 OK {...} GET /foo/bar500 Sever error x429 Too many requests
- 25. @aliostad Anti-Pattern Transparent Server GET /foo/bar 200 OK {...} GET /foo/bar503 Service Unavailable {“errorText”:“Above rate limit. Try again later”}xx x x ✓ ✓ ✓ ?
- 26. @aliostad Anti-Pattern Transparent Server GET /foo/bar 202 Accepted Location: /foo/bar/12345678 ETA: 80 ?
- 27. @aliostad Anti-Pattern Transparent Server GET /foo/bar 200 OK {...} 202 AcceptedLocation: /foo/bar/12345678 ETA: 86 GET /foo/bar ✓
- 29. @aliostad “client enforces its special needs onto the API signature” Anti-Pattern Demanding Client certain clients limitations (or reluctance to implement) become server's default behaviour
- 30. @aliostad E x a m p l e s Anti-Pattern Demanding Client Client enforces use of query string over HTTP headers1 2 Client pushes for consistency of parameter names with other [external] APIs 3 Client pushes for consistency of behaviour with other [external] APIs 4 Client asks for simpler model since does not need the extra data
- 32. @aliostad “server assumes the role of defining client experience” Anti-Pattern Assuming Server server makes decisions on issues that are inherently client concerns
- 33. @aliostad E x a m p l e 1 Anti-Pattern Assuming Server GET /api/catalogue/products/page1 GET /api/catalogue/products/page2 x
- 34. @aliostad E x a m p l e 1 Anti-Pattern Assuming Server GET /api/catalogue/products?from=1&count=30 ✓
- 35. @aliostad E x a m p l e 2 Anti-Pattern Assuming Server B r o w s e r s n i f f i n g
- 37. @aliostad “client takes on responsibilities that cannot fulfil” Anti-Pattern Presumptuous Client Client presumes it can fulfil some responsibilities that are inherently server’s
- 38. @aliostad E x a m p l e s Client implements an algorithm that needs to be centralised on server1 2 Client act as an authority for authentication or authorisation 3 Client takes control of cache invalidation Anti-Pattern Presumptuous Client
- 39. @aliostad 5 Anti-Pattern Summary Chauvinist Server: designing from server’s perspectives1 2 Transparent Server: server exposing its internals 3 Demanding Client: client limitation shaping API signature 4 Assuming Server: server defining user experience 5 Presumptuous Client: client taking on responsibilities that cannot fulfil
- 41. Acknowledgments Resources CSDS: http://byterot.blogspot.ro/2012/11/client-server-domain-separation-csds-rest.html* * REST: https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf * Pictures https://www.flickr.com/photos/fazen/9079179 https://www.flickr.com/photos/dinnerseries/16479210485 https://www.flickr.com/photos/ashley-rly/3768328487 https://www.flickr.com/photos/gazeronly/13898117729 https://www.flickr.com/photos/warrenlynn/2715823110 https://www.flickr.com/photos/mr_t_in_dc/4548498209