5 anti-patterns in api design - ndc london 2016
TRANSCRIPT
API DESIGN
5 Anti-Patternsin
Ali
@aliostadKheyrollahi
W iiiiiiire Wiie
5 Anti-PatternsWho Are We ASOS
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.
5 Anti-PatternsIn Numbers ASOS
~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
API The Art of Presentation
API, API . . .
. . . everywhere
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
@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
REST Stateless
REST Layered Architecture
REST Caching
@aliostad
Resources and representations
REST Uniform Interface
S e l f - d e s c r i p t i v e
messages
Hypermedia
@aliostad
REST Client-Server
@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
@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
@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
@aliostad
Client-Server Boundary
Bou
ndar
y
@aliostad
CSDS Client-Server Domain Separation
“ Client and server must define and live within their
own bounded context ”
CSDS Client-Server Domain Separation
S e r v e r
API Restaurant
@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
@aliostad
Client-Server Boundary
Bou
ndar
y
Anti-Pattern Transparent Server
1
“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
@aliostad
E x a m p l e 1
Anti-Pattern Transparent Server
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
@aliostad
E x a m p l e 2
POST /ba
skets?ci
d=908
201 CreatedLocation: /baskets/123435455456
POST /baskets/123435455456{...}200 OKx
Anti-Pattern Transparent Server
@aliostad
E x a m p l e 2
POST cus
tomer/me
/basket
{…}
200 OK✓Anti-Pattern Transparent Server
Anti-Pattern Chauvinist Server
2
“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
@aliostad
Anti-Pattern Chauvinist Server
H A T E O A S (and not hypermedia itself)
Hypermedia as the Engine
of Application (state)
Anti-Pattern Chauvinist Server
H A T E O A SClient 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
Anti-Pattern Chauvinist Server
H A T E O A S? R e a l l y ? ?
Anti-Pattern Demanding Client
3
“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
@aliostad
Anti-Pattern Demanding Client
GET /api/catalogue/products.xmlGET /api/catalogue/products.json
GET /api/catalogue/products?format=xmlGET /api/catalogue/products?format=jsonx
E x a m p l e 1
Bioenergy KDF REST API
@aliostad
Anti-Pattern Demanding Client
GET /api/catalogue/productsAccept: application/json
E x a m p l e 1
✓
@aliostad
Anti-Pattern Demanding Client
E x a m p l e 2
GET /api/catalogue/products?client=mobile
GET /api/catalogue/products?model=summaryx
@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
Anti-Pattern Assuming Server
4
“server assumes the role of defining client experience”
Anti-Pattern Assuming Server
server makes decisions on issues that are inherently client concerns
@aliostad
E x a m p l e 1
Anti-Pattern Assuming Server
GET /api/catalogue/products/pages/1GET /api/catalogue/products/pages/2x
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
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
Anti-Pattern Presumptuous Client
5
“client takes on responsibilities that cannot fulfil”
Anti-Pattern Presumptuous Client
Client presumes it can fulfil some responsibilities that are inherently server’s
E x a m p l e s
Anti-Pattern Presumptuous Client
A P I
Identity
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
E x a m p l e s
Anti-Pattern Presumptuous Client
I D S E R V E RID Token
ID Request
A P I
Access TokenAccess Token
. . . ID Token✓
@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
@aliostad
Microservices take importance of APIs to a new level 1
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
Thank You
@aliostad
http://byterot.blogspot.com