http://www.egeniq.com
[email protected]
@egeniq
Code By The Sea November 3, 2015
Ivo Jansch
Scenario Driven API Design
Or: how to make more usable APIs
Slide 2
Slide 2 text
About Me
@ijansch
Entreprenerd
(@egeniq / @buildozerapp)
App & Api Developer
Author & Speaker
Upcoming:
http://leanpub.com/nways
Conference Organizer
(@endpointcon / @mdevcon)
2
Slide 3
Slide 3 text
About Egeniq
3
Slide 4
Slide 4 text
About Buildozer
4
Checkout Validation Distribution
Code
Buildozer
http://buildozer.io
Continuous Integration for apps
Slide 5
Slide 5 text
A few months ago:
“We have some issues.
Can you fix our
performance problem?”
5
An interesting, anonymous case
Slide 6
Slide 6 text
REST API (PHP)
Their design
6
SQL database
Models
Controllers Views
/orders
/products
/orders/:id/products
/products/:id
etc
Slide 7
Slide 7 text
Website (YUI)
REST API (PHP)
The design
7
SQL database
Models
Controllers Views
API client
Models
Controllers Views
Slide 8
Slide 8 text
What did a trace show?
1 dashboard page
26
API calls
124 objects passed between api and client
8
Slide 9
Slide 9 text
WTF
“No. I can not fix your performance problem”
“But, but.. our API is so RESTful!”
9
Slide 10
Slide 10 text
Website (YUI based)
REST API (PHP based)
Problem
10
SQL database
Models
Controllers Views
API client
Models
Controllers Views
1x
26x
Slide 11
Slide 11 text
Website
REST API
Problem
11
SQL database
THIN BUSINESS LOGIC
Controllers Views
API client
THICK BUSINESS LOGIC
Controllers Views
Slide 12
Slide 12 text
Something went terribly wrong
12
SELECT * FROM order WHERE id = 2
orderBean.selectById(2)
$orderModel->getOrder(2)
http://api/orders/2
RESTful APIs
Slide 13
Slide 13 text
OMG
Give the monkey a screwdriver.
Prepare to get hurt.
13
Slide 14
Slide 14 text
Website
REST API
What if we add even more clients?
14
SQL database
THIN BUSINESS LOGIC
Controllers Views
API client
THICK BUSINESS LOGIC
Controllers Views
Mobile
Client?
Slide 15
Slide 15 text
Important
This is not a REST problem.
REST is a great way to expose an API.
15
Slide 16
Slide 16 text
Important
However:
REST is NOT an excuse
to expose your raw data model
16
Slide 17
Slide 17 text
Important
REST is NOT an excuse
to stop thinking about business logic
17
Slide 18
Slide 18 text
Introducing ‘Scenario Driven API Design’
18
Slide 19
Slide 19 text
Data Driven Design
19
Data Modeling
API interface (REST/HAL/..)
Generic Clients
Slide 20
Slide 20 text
Client Driven Design
20
Data Modeling
API interface (REST/HAL/..)
Specific Clients
Slide 21
Slide 21 text
Scenario Driven Design
21
Data Modeling
Interface Design
Specific/Generic Clients
Service Design
Slide 22
Slide 22 text
Scenario Driven Design
‣1. Client analysis
‣Identify client needs
‣Usage scenarios
‣2. Service design
‣Optimal ways to service the client scenarios
‣3. Data modelling
‣Create data model to support the scenario’s
‣Low level and high level concepts
‣4. Interface design
‣REST/HAL etc. interface
‣Versioning, etc.
22
Slide 23
Slide 23 text
Teach by example: Pathé Thuis
23
Slide 24
Slide 24 text
Big ecosystem, lots of clients
24
API
ipad tv web xbox
android ???
Slide 25
Slide 25 text
Typical VOD features
25
My rented movies
Featured movies
Featured movie collections
Recommendations
Popular movies
Slide 26
Slide 26 text
Would this work?
‣Data Driven:
‣GET /movies/:id
‣GET /tickets
‣GET /users/:id
‣Yes it would work
‣but we would easily get stuck with the ’26 api calls’
problem
26
Slide 27
Slide 27 text
Scenario Driven Design
‣Identify all relevant scenarios:
‣Order a movie
‣Watch a movie
‣See list of my movies
‣Promote content on the home screen
‣See what’s available
‣Like/unlike movies
‣Interactions are platform-specific, scenarios
usually aren’t.
27
Slide 28
Slide 28 text
“Promote content on the home screen”
‣All clients should present, on their home
screen, after login:
‣The user’s most recently rented movies
‣User specific recommendations
‣Movie top 20
‣Featured movies
28
Slide 29
Slide 29 text
Scenario Driven Design
29
Data Modeling
API interface
Specific/Generic
Clients
Service Design
1. ’home’ screen
Slide 30
Slide 30 text
Scenario Driven Design
30
Data Modeling
API interface
Specific/Generic
Clients
Service Design 2. Promote content on
the home screen
1. ’home’ screen
Scenario Driven Design
32
Data Modeling
API interface
Specific/Generic
Clients
Service Design 2. Promote content on
the home screen
3. Movies, collections, banners
1. ’home’ screen
Slide 33
Slide 33 text
Scenario Driven Design
33
Data Modeling
API interface
Specific/Generic
Clients
Service Design 2. Promote content on
the home screen
3. Movies, collections, banners
4. /promoslots/home
1. ’home’ screen
Slide 34
Slide 34 text
The interface
‣/recommendations
• or /users/@me/recommendations
‣/promoslots/:screen
‣/users/@me/movies
‣/users/@me/movies/liked
‣/movies
34
Interesting concept: Pseudo identifiers
compound resources
views
Slide 35
Slide 35 text
Consider scenario’s at the highest level
‣GET /users/@me/dashboard
‣High Level Scenario
‣Business Logic entirely API side
‣Important: find balance between generic
and specific
35
Slide 36
Slide 36 text
Wise Words
‣Eric S. Raymond: “Smart data and dumb
code works a lot better than the other way
around” (from: The Cathedral & The
Bazaar)
‣In 2015 this means:
Smart APIs, dumb clients
36
Slide 37
Slide 37 text
Client
REST API
Business Logic where it belongs
37
Data
BUSINESS LOGIC
Controllers Views
API client
Controllers Views
Look mum, no business logic!
Slide 38
Slide 38 text
Seen in a project evaluation
38
Slide 39
Slide 39 text
Consider This
API Usability over API RESTfulness
and
Scenarios first, formatting second
39
Slide 40
Slide 40 text
Standardisation
JSON-API
http://jsonapi.org
HAL
http://stateless.co/hal_specification.html
40
Slide 41
Slide 41 text
A word about tool vendors
41
Data Modeling
Interface Design
Specific/Generic Clients
Service Design
db vendor space
(commoditised
~ 16 years ago)
api tool vendor space
(to be commoditised)
you
Slide 42
Slide 42 text
Some Myths Debunked
42
Slide 43
Slide 43 text
Myth 1
I don’t know how
my API will be used
43
Slide 44
Slide 44 text
Myth 2
If my features change,
my entire API must change
44