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
@aliostadKheyrollahi

2. W iiiiiiire Wiie
5 Anti-PatternsWho Are WeASOS
ASOS is a global fashion
destination for 20-somethings.
From fashion advice, stories
and inspiration, to more than
80,000 products available to
buy on any device, ASOS, with
its unbeatable service, is a true
home for fashion lovers.

3. 5 Anti-PatternsIn NumbersASOS
~1 bln Turnover (£)
1.1 bln visits / year
9.9 mln Active customers
58% International
3.7 M
3.3 M
2.4 M
885 K

4. API The Art of Presentation

5. API, API . . .
. . . everywhere

6. 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

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

8. REST Stateless

9. REST Layered Architecture

10. REST Caching

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

12. @aliostad
REST Client-Server

13. @aliostad
HTTP Client-Server
GET /api/catalogue/products/123456
GET /api/catalogue/Products/123456
S e r v e r C o n c e r n

14. @aliostad
HTTP Client-Server
GET /api/catalogue/Products/123456
301 Moved Permanently
Location /api/catalogue/products/123456
C l i e n t C o n c e r n
GET /api/catalogue/Products/123456
???
1
2

15. @aliostad
HTTP Client-Server
M i x e d C o n c e r n
GET /api/catalogue/Products/123456
200 OK
max-age: 300
GET /api/catalogue/Products/123456
If-Modified-Since: Fri, 15 Jan 2016 10:28:16 GMT
304 Not Modified

16. @aliostad
Client-Server Boundary
Boundary

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

18. CSDS Client-Server Domain Separation
S e r v e r

19. API Restaurant

21. @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 Server’s public domain (Resource Comprehension)
Normally keeps state but does not master it4

22. @aliostad
Client-Server Boundary
Boundary

24. Anti-Pattern Transparent Server
1

25. “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

26. @aliostad
E x a m p l e 1
Anti-Pattern Transparent Server

27. 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

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

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

30. Anti-Pattern Chauvinist Server
2

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

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

33. Anti-Pattern Chauvinist Server
H A T E O A S
Client most likely a server [wasteful to navigate]2
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

34. Anti-Pattern Chauvinist Server
H A T E O A S?
R e a l l y ? ?

35. Anti-Pattern Demanding Client
3

36. “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

37. @aliostad
Anti-Pattern Demanding Client
GET /api/catalogue/products.xml
GET /api/catalogue/products.json
GET /api/catalogue/products?format=xml
GET /api/catalogue/products?format=json
x
E x a m p l e 1
Bioenergy KDF
REST API

38. @aliostad
Anti-Pattern Demanding Client
GET /api/catalogue/products
Accept: application/json
E x a m p l e 1
✓

39. @aliostad
Anti-Pattern Demanding Client
E x a m p l e 2
GET /api/catalogue/products?client=mobile
GET /api/catalogue/products?model=summary
x

40. @aliostad
Anti-Pattern Demanding Client
E x a m p l e 2
✓GET /api/catalogue/products?fields=foo,bar,jazz
GET /api/catalogue/products_summary

41. Anti-Pattern Assuming Server
4

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

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

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

45. 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

46. Anti-Pattern Presumptuous Client
5

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

48. E x a m p l e s
Anti-Pattern Presumptuous Client
A P I
Identity

49. E x a m p l e s
Anti-Pattern Presumptuous Client
I D S E R V E R
Long Expiry Token
ID Request
A P I
Token

50. E x a m p l e s
Anti-Pattern Presumptuous Client
I D S E R V E R
ID Token
ID Request
A P I
Access TokenAccess Token
. . .
ID Token
✓

51. @aliostad
E x a m p l e s
Client act as an authority for authentication or authorisation1
2 Client implements an algorithm that needs to be centralised on server
3 Client takes control of cache invalidation
Anti-Pattern Presumptuous Client

52. @aliostad
Microservices take importance of APIs to a new level1
2 Think of your API as a restaurant and remember the contrast with kitchen
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

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