5 anti-patterns in api design - buildstuff - schedschd.ws/hosted_files/buildstuff15lithuania/59/ali...
TRANSCRIPT
![Page 1: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/1.jpg)
API DESIGN
5 Anti-Patternsin
Ali @
aliostadKheyrollahi
![Page 2: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/2.jpg)
API The Art of Presentation
![Page 3: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/3.jpg)
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 4: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/4.jpg)
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 5: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/5.jpg)
REST Stateless
![Page 6: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/6.jpg)
@aliostad
REST Layered Architecture
![Page 7: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/7.jpg)
REST Caching
![Page 8: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/8.jpg)
@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 9: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/9.jpg)
@aliostad
REST Client-Server
![Page 10: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/10.jpg)
@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
![Page 11: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/11.jpg)
@aliostad
Client-Server Boundary
Bou
ndar
y
![Page 12: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/12.jpg)
@aliostad
CSDS Client-Server Domain Separation
“ Client and server must define and live within their
own bounded context ”
![Page 13: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/13.jpg)
@aliostad
CSDS Client-Server Domain Separation
S e r v e r
![Page 14: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/14.jpg)
API Restaurant
![Page 15: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/15.jpg)
![Page 16: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/16.jpg)
@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
![Page 17: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/17.jpg)
@aliostad
Client-Server Boundary
Bou
ndar
y
![Page 18: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/18.jpg)
@aliostad
![Page 19: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/19.jpg)
@aliostad
Anti-Pattern Transparent Server
1
![Page 20: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/20.jpg)
@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
![Page 21: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/21.jpg)
E x a m p l e 1
Anti-Pattern Transparent Server
![Page 22: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/22.jpg)
@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
![Page 23: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/23.jpg)
@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 24: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/24.jpg)
@aliostad
E x a m p l e 2
POST cus
tomer/me
/basket
{…}
200 OK✓Anti-Pattern Transparent Server
![Page 25: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/25.jpg)
@aliostad
Anti-Pattern Chauvinist Server
2
![Page 26: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/26.jpg)
@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
![Page 27: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/27.jpg)
@aliostad
Anti-Pattern Chauvinist Server
H A T E O A S (and not hypermedia itself)
Hypermedia as the Engine
of Application (state)
![Page 28: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/28.jpg)
@aliostad
Anti-Pattern Chauvinist Server
H A T E O A SClient 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
![Page 29: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/29.jpg)
@aliostad
Anti-Pattern Chauvinist Server
H A T E O A S?
![Page 30: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/30.jpg)
@aliostad
Anti-Pattern Demanding Client
3
![Page 31: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/31.jpg)
@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
![Page 32: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/32.jpg)
@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
![Page 33: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/33.jpg)
@aliostad
Anti-Pattern Assuming Server
4
![Page 34: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/34.jpg)
@aliostad
“server assumes the role of defining client experience”
Anti-Pattern Assuming Server
server makes decisions on issues that are inherently client concerns
![Page 35: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/35.jpg)
@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 36: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/36.jpg)
@aliostad
E x a m p l e 1
Anti-Pattern Assuming Server
GET /api/catalogue/products?from=1&count=30✓
![Page 37: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/37.jpg)
@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
![Page 38: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/38.jpg)
@aliostad
Anti-Pattern Presumptuous Client
5
![Page 39: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/39.jpg)
@aliostad
“client takes on responsibilities that cannot fulfil”
Anti-Pattern Presumptuous Client
Client presumes it can fulfil some responsibilities that are inherently server’s
![Page 40: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/40.jpg)
@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
![Page 41: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/41.jpg)
@aliostad
Microservices take importance of APIs to a new level 1
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
![Page 42: 5 Anti-Patterns in API Design - buildstuff - Schedschd.ws/hosted_files/buildstuff15lithuania/59/Ali Kheyrollahi - 5... · REST Stateless. @aliostad ... 6 Microservices: servers smaller,](https://reader033.vdocument.in/reader033/viewer/2022051718/5a723b437f8b9abb538d5d53/html5/thumbnails/42.jpg)
Thank You
@aliostad
http://byterot.blogspot.com