5 Anti-Patterns in API Design

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

Transcript of 5 Anti-Patterns in API Design

API DESIGN

5 Anti-Patternsin

Ali @

aliostadKheyrollahi

@aliostad

REST

CSDS

ANTI-PATTERNS

MORE ANTI-PATTERNS

Summary

Q’s

REST Stateless

@aliostad

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

REST Client-Server

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

@aliostad

CSDS Client-Server Domain Separation

S e r v e r

Server - Not just

a thin shell around a

d a t a b a s e

@aliostad

CSDS Client-Server Domain Separation

S e r v e r

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

@aliostad

Client-Server Boundary

Bou

ndar

y

@aliostad

@aliostad

Anti-Pattern Chauvinist Server

1

@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

@aliostad

Anti-Pattern Chauvinist Server

E x a m p l e

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

@aliostad

Anti-Pattern Chauvinist Server

E x a m p l e

POST /ba

skets?ci

d=908

201 CreatedLocation: /basket/123435455456

POST /baskets/123435455456{...}200 OKx

@aliostad

Anti-Pattern Chauvinist Server

E x a m p l e

POST cus

tomer/me

/basket

{…}

200 OK✓

@aliostad

Anti-Pattern Transparent Server

2

@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

@aliostad

Anti-Pattern Transparent Server

GET /foo

/bar

200 OK

{...}

GET /foo/bar500 Sever errorx429 Too many requests

@aliostad

Anti-Pattern Transparent Server

GET /foo

/bar

200 OK

{...}

GET /foo/bar503 Service Unavailable{“errorText”:“Above rate

limit. Try again later”}xxx

x

✓✓

?

@aliostad

Anti-Pattern Transparent Server

GET /foo

/bar

202 Accepted

Location: /foo/bar/12345678ETA: 80?

@aliostad

Anti-Pattern Transparent Server

GET /foo

/bar

200 OK

{...}

202 AcceptedLocation: /foo/bar/12345678

ETA: 86

GET /foo/bar✓

@aliostad

Anti-Pattern Demanding Client

3

@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

@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

@aliostad

Anti-Pattern Assuming Server

4

@aliostad

“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/page1GET /api/catalogue/products/page2x

@aliostad

E x a m p l e 1

Anti-Pattern Assuming Server

GET /api/catalogue/products?from=1&count=30✓

@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

@aliostad

Anti-Pattern Presumptuous Client

5

@aliostad

“client takes on responsibilities that cannot fulfil”

Anti-Pattern Presumptuous Client

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

@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

@aliostad

5 Anti-Pattern Summary

Chauvinist Server: designing from server’s perspectives1

2 Transparent Server: server exposing its internals

3 Demanding Client: client limitation shaping API signature

4 Assuming Server: server defining user experience

5 Presumptuous Client: client taking on responsibilities that cannot fulfil

Thank You!

Ali @

aliostadKheyrollahi

http://byterot.blogspot.com

Acknowledgments Resources

CSDS: http://byterot.blogspot.ro/2012/11/client-server-domain-separation-csds-rest.html*

* REST: https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf

* Pictures

https://www.flickr.com/photos/fazen/9079179

https://www.flickr.com/photos/dinnerseries/16479210485

https://www.flickr.com/photos/ashley-rly/3768328487

https://www.flickr.com/photos/gazeronly/13898117729

https://www.flickr.com/photos/warrenlynn/2715823110

https://www.flickr.com/photos/mr_t_in_dc/4548498209