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)

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

5. REST Stateless

6. @aliostad
REST Layered Architecture

7. REST Caching

8. @aliostad
Resources and
representations
REST Uniform Interface
S e l f - d e s c r i p t i v e
messages
Hypermedia

9. @aliostad
REST Client-Server

10. @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

11. @aliostad
Client-Server Boundary
Boundary

12. @aliostad
CSDS Client-Server Domain Separation
“ Client and server must
define and live within their
own bounded context ”

13. @aliostad
CSDS Client-Server Domain Separation
S e r v e r

14. API Restaurant

16. @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

17. @aliostad
Client-Server Boundary
Boundary

18. @aliostad

19. @aliostad
Anti-Pattern Transparent Server
1

20. @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

21. E x a m p l e 1
Anti-Pattern Transparent Server

22. @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

23. @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

24. @aliostad
E x a m p l e 2
POST customer/me/basket
{…}
200 OK
✓
Anti-Pattern Transparent Server

25. @aliostad
Anti-Pattern Chauvinist Server
2

26. @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

27. @aliostad
Anti-Pattern Chauvinist Server
H A T E O A S(and not hypermedia itself)
Hypermedia
as the Engine
of Application (state)

28. @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
6 Microservices: servers smaller, containing a couple of resources
4 Undefined caching directives for hypermedia
Server hasn’t got a clue what the application is1
5 Don’t try to spare the client composing URLs

29. @aliostad
Anti-Pattern Chauvinist Server
H A T E O A S?

30. @aliostad
Anti-Pattern Demanding Client
3

31. @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

32. @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

33. @aliostad
Anti-Pattern Assuming Server
4

34. @aliostad
“server assumes the role of
defining client experience”
Anti-Pattern Assuming Server
server makes decisions on issues that are
inherently client concerns

35. @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

36. @aliostad
E x a m p l e 1
Anti-Pattern Assuming Server
GET /api/catalogue/products?from=1&count=30
✓

37. @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

38. @aliostad
Anti-Pattern Presumptuous Client
5

39. @aliostad
“client takes on responsibilities
that cannot fulfil”
Anti-Pattern Presumptuous Client
Client presumes it can fulfil some responsibilities that are
inherently server’s

40. @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

41. @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

42. Thank You
@aliostad
http://byterot.blogspot.com