5 anti-patterns in api design - ndc london 2016

53
API DESIGN 5 Anti-Patterns in Ali @aliostad Kheyrollahi

Upload: ali-kheyrollahi

Post on 07-Apr-2017

753 views

Category:

Software


2 download

TRANSCRIPT

Page 1: 5 Anti-Patterns in Api Design - NDC London 2016

API DESIGN

5 Anti-Patternsin

Ali

@aliostadKheyrollahi

Page 2: 5 Anti-Patterns in Api Design - NDC London 2016

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.

Page 3: 5 Anti-Patterns in Api Design - NDC London 2016

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

Page 4: 5 Anti-Patterns in Api Design - NDC London 2016

API The Art of Presentation

Page 5: 5 Anti-Patterns in Api Design - NDC London 2016

API, API . . .

. . . everywhere

Page 6: 5 Anti-Patterns in Api Design - NDC London 2016

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

Page 7: 5 Anti-Patterns in Api Design - NDC London 2016

@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

Page 8: 5 Anti-Patterns in Api Design - NDC London 2016

REST Stateless

Page 9: 5 Anti-Patterns in Api Design - NDC London 2016

REST Layered Architecture

Page 10: 5 Anti-Patterns in Api Design - NDC London 2016

REST Caching

Page 11: 5 Anti-Patterns in Api Design - NDC London 2016

@aliostad

Resources and representations

REST Uniform Interface

S e l f - d e s c r i p t i v e

messages

Hypermedia

Page 12: 5 Anti-Patterns in Api Design - NDC London 2016

@aliostad

REST Client-Server

Page 13: 5 Anti-Patterns in Api Design - NDC London 2016

@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

Page 14: 5 Anti-Patterns in Api Design - NDC London 2016

@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

Page 15: 5 Anti-Patterns in Api Design - NDC London 2016

@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

Page 16: 5 Anti-Patterns in Api Design - NDC London 2016

@aliostad

Client-Server Boundary

Bou

ndar

y

Page 17: 5 Anti-Patterns in Api Design - NDC London 2016

@aliostad

CSDS Client-Server Domain Separation

“ Client and server must define and live within their

own bounded context ”

Page 18: 5 Anti-Patterns in Api Design - NDC London 2016

CSDS Client-Server Domain Separation

S e r v e r

Page 19: 5 Anti-Patterns in Api Design - NDC London 2016

API Restaurant

Page 20: 5 Anti-Patterns in Api Design - NDC London 2016
Page 21: 5 Anti-Patterns in Api Design - NDC London 2016

@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

Page 22: 5 Anti-Patterns in Api Design - NDC London 2016

@aliostad

Client-Server Boundary

Bou

ndar

y

Page 23: 5 Anti-Patterns in Api Design - NDC London 2016
Page 24: 5 Anti-Patterns in Api Design - NDC London 2016

Anti-Pattern Transparent Server

1

Page 25: 5 Anti-Patterns in Api Design - NDC London 2016

“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

Page 26: 5 Anti-Patterns in Api Design - NDC London 2016

@aliostad

E x a m p l e 1

Anti-Pattern Transparent Server

Page 27: 5 Anti-Patterns in Api Design - NDC London 2016

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

Page 28: 5 Anti-Patterns in Api Design - NDC London 2016

@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

Page 29: 5 Anti-Patterns in Api Design - NDC London 2016

@aliostad

E x a m p l e 2

POST cus

tomer/me

/basket

{…}

200 OK✓Anti-Pattern Transparent Server

Page 30: 5 Anti-Patterns in Api Design - NDC London 2016

Anti-Pattern Chauvinist Server

2

Page 31: 5 Anti-Patterns in Api Design - NDC London 2016

“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

Page 32: 5 Anti-Patterns in Api Design - NDC London 2016

@aliostad

Anti-Pattern Chauvinist Server

H A T E O A S (and not hypermedia itself)

Hypermedia as the Engine

of Application (state)

Page 33: 5 Anti-Patterns in Api Design - NDC London 2016

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

Page 34: 5 Anti-Patterns in Api Design - NDC London 2016

Anti-Pattern Chauvinist Server

H A T E O A S? R e a l l y ? ?

Page 35: 5 Anti-Patterns in Api Design - NDC London 2016

Anti-Pattern Demanding Client

3

Page 36: 5 Anti-Patterns in Api Design - NDC London 2016

“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

Page 37: 5 Anti-Patterns in Api Design - NDC London 2016

@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

Page 38: 5 Anti-Patterns in Api Design - NDC London 2016

@aliostad

Anti-Pattern Demanding Client

GET /api/catalogue/productsAccept: application/json

E x a m p l e 1

Page 39: 5 Anti-Patterns in Api Design - NDC London 2016

@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

Page 40: 5 Anti-Patterns in Api Design - NDC London 2016

@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

Page 41: 5 Anti-Patterns in Api Design - NDC London 2016

Anti-Pattern Assuming Server

4

Page 42: 5 Anti-Patterns in Api Design - NDC London 2016

“server assumes the role of defining client experience”

Anti-Pattern Assuming Server

server makes decisions on issues that are inherently client concerns

Page 43: 5 Anti-Patterns in Api Design - NDC London 2016

@aliostad

E x a m p l e 1

Anti-Pattern Assuming Server

GET /api/catalogue/products/pages/1GET /api/catalogue/products/pages/2x

Page 44: 5 Anti-Patterns in Api Design - NDC London 2016

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

Page 45: 5 Anti-Patterns in Api Design - NDC London 2016

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

Page 46: 5 Anti-Patterns in Api Design - NDC London 2016

Anti-Pattern Presumptuous Client

5

Page 47: 5 Anti-Patterns in Api Design - NDC London 2016

“client takes on responsibilities that cannot fulfil”

Anti-Pattern Presumptuous Client

Client presumes it can fulfil some responsibilities that are inherently server’s

Page 48: 5 Anti-Patterns in Api Design - NDC London 2016

E x a m p l e s

Anti-Pattern Presumptuous Client

A P I

Identity

Page 49: 5 Anti-Patterns in Api Design - NDC London 2016

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

Page 50: 5 Anti-Patterns in Api Design - NDC London 2016

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✓

Page 51: 5 Anti-Patterns in Api Design - NDC London 2016

@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

Page 52: 5 Anti-Patterns in Api Design - NDC London 2016

@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

Page 53: 5 Anti-Patterns in Api Design - NDC London 2016

Thank You

@aliostad

http://byterot.blogspot.com