5 Anti-Patterns in API Design - DDD East Anglia 2015
0 likes715 views
This document discusses 5 anti-patterns to avoid when designing APIs: 1. Transparent Server - Exposing internal implementation details in the public API. 2. Chauvinist Server - Designing the API from the server's perspective and pushing the client to conform. 3. Demanding Client - Enforcing special client needs or limitations onto the API signature. 4. Assuming Server - Making assumptions about the client experience that should be client-defined. 5. Presumptuous Client - Taking on responsibilities inherently meant for the server.
![@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](https://image.slidesharecdn.com/5anti-patternsinapidesign-dddeastanglia-150928151754-lva1-app6891/85/5-Anti-Patterns-in-API-Design-DDD-East-Anglia-2015-27-320.jpg)
5 Anti-Patterns in API Design - DDD East Anglia 2015
- 1. API DESIGN 5 Anti-Patterns in Ali @aliostad Kheyrollahi
- 2. API The Art of Presentation
- 3. API Iceberg “This huge mass underneath the water that you can't see, the private API, is the biggest part of the whole opportunity.” Daniel Jacobson, Netflix - 2011
- 4. Micro services “ … the microservice architectural style is an approach to developing a single application as a suite of small services, each running in its own process and communicating with lightweight mechanisms, often an HTTP resource API” Martin Fowler - Bliki
- 7. @aliostad HTTP Client-Server Server Concern: e.g. returning the resource when requested with a different casing /car/123 vs /Car/123 Client Concern: e.g. Handling 301 (moved permanently) Mixed Concern: e.g. Most HTTP concepts such as Content Negotiation or Caching/Concurrency
- 8. @aliostad CSDS Client-Server Domain Separation S e r v e r
- 9. @aliostad CSDS Client-Server Domain Separation “ Client and server must define and live within their own bounded context ”
- 10. API Restaurant
- 12. @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 it4
- 14. @aliostad
- 16. @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
- 17. E x a m p l e 1 Anti-Pattern Transparent Server
- 18. @aliostad E x a m p l e 2 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 Anti-Pattern Transparent Server
- 19. @aliostad E x a m p l e 2 POST /baskets?cid=908 201 Created Location: /baskets/123435455456 POST /baskets/123435455456 {...}200 OK x Anti-Pattern Transparent Server
- 20. @aliostad E x a m p l e 2 POST customer/me/basket {…} 200 OK ✓ Anti-Pattern Transparent Server
- 22. @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
- 23. @aliostad Anti-Pattern Chauvinist Server H A T E O A S Hypermedia as the Engine of Application (state)
- 24. @aliostad Anti-Pattern Chauvinist Server H A T E O A S Client most likely a server wasteful to navigate2 3 Client uses more than one server 4 Microservices: servers smaller, containing a couple of resources 5 Undefined caching directives for hypermedia Server hasn’t got a clue what the application is1
- 26. @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
- 27. @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
- 29. @aliostad “server assumes the role of defining client experience” Anti-Pattern Assuming Server server makes decisions on issues that are inherently client concerns
- 30. @aliostad E x a m p l e 1 Anti-Pattern Assuming Server GET /api/catalogue/products/pages/1 GET /api/catalogue/products/pages/2 x
- 31. @aliostad E x a m p l e 1 Anti-Pattern Assuming Server GET /api/catalogue/products?from=1&count=30 ✓
- 32. @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
- 34. @aliostad “client takes on responsibilities that cannot fulfil” Anti-Pattern Presumptuous Client Client presumes it can fulfil some responsibilities that are inherently server’s
- 35. @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
- 36. @aliostad Microservices take importance of APIs to a new level1 2 Think of your API as a restaurant and remember the contrast 3 Transparent Server: Exposing internals Re Cap 4 Chauvinist Server: Client becoming a subordinate 5 Demanding Client: Client enforcing special needs to API signature 6 Assuming Server: Server deciding client experience 7 Presumptuous Client: Client taking responsibilities cannot fulfil