Scenario Driven API Design (Apidays Paris)

In this talk we will look at an approach to API design that I have been practicing and refining for the past couple of years. We will look at what Scenario Driven Design means, when it is useful, and what the advantages and disadvantages are, when comparing this design approach with other API design methodologies. We will see how it will aid developers that need to create APIs for a large range of devices and offer advice on how to create APIs that are useful and usable.

Transcript

1. http://www.egeniq.com info@egeniq.com @egeniq APIDays Paris, December 2, 2014 Ivo Jansch Scenario Driven API Design Or: how to make more usable APIs
2. About Me @ijansch Entreprenerd (@egeniq / @buildozerapp) App & Api Developer Author & Speaker Upcoming: 
 http://leanpub.com/nways Conference Organizer (@endpointcon / @mdevcon) 2
3. About Egeniq Apps & Apis for clients 3
4. About Buildozer 4 Checkout Validation Distribution Code Buildozer http://buildozer.io Continuous Integration for apps
5. A few months ago: “We have some issues. Can you fix our performance problem?” 5 An interesting, anonymous case
6. REST API (PHP) Their design 6 SQL database Models Controllers Views /orders /products /orders/:id/products /products/:id etc
7. Website (YUI) REST API (PHP) The design 7 SQL database Models Controllers Views API client Models Controllers Views
8. What did a trace show? 1 dashboard page 26 API calls 124 objects passed between api and client 8
9. WTF “No. I can not fix your performance problem” “But, but.. our API is so RESTful!” 9
10. Website (YUI based) REST API (PHP based) Problem 10 SQL database Models Controllers Views API client Models Controllers Views 1x 26x
11. Website REST API Problem 11 SQL database THIN BUSINESS LOGIC Controllers Views API client THICK BUSINESS LOGIC Controllers Views
12. Something went terribly wrong 12 SELECT * FROM order WHERE id = 2 orderBean.selectById(2) $orderModel->getOrder(2) http://api/orders/2 RESTful APIs
13. OMG Give the monkey a screwdriver. Prepare to get hurt. 13
14. 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?
15. Important This is not a REST problem. REST is a great way to expose an API. 15
16. Important However: REST is NOT an excuse to expose your raw data model 16
17. Important REST is NOT an excuse to stop thinking about business logic 17
18. Introducing ‘Scenario Driven API Design’ 18
19. Data Driven Design 19 Data Modeling API interface (REST/HAL/..) Generic Clients
20. Client Driven Design 20 Data Modeling API interface (REST/HAL/..) Specific Clients
21. Scenario Driven Design 21 Data Modeling Interface Design Specific/Generic Clients Service Design
22. 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
23. Teach by example: Pathé Thuis 23
24. Big ecosystem, lots of clients 24 API ipad tv web xbox android ???
25. Typical VOD features 25 My rented movies Featured movies Featured movie collections Recommendations Popular movies
26. 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
27. 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
28. “Promote content on the home page” ‣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
29. Scenario Driven Design 29 Data Modeling API interface Specific/Generic Clients Service Design 1. ’home’ screen
30. Scenario Driven Design 30 Data Modeling API interface Specific/Generic Clients Service Design 2. Promote content on the home screen 1. ’home’ screen
31. Scenario Driven Design 31 Movie Banner Promoslot Collection Screen (home, profile) Purchase
32. 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
33. 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
34. 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
35. 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
36. 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 2014 this means: 
 
 Smart APIs, dumb clients 36
37. Client REST API Business Logic where it belongs 37 Data BUSINESS LOGIC Controllers Views API client Controllers Views Look mum, no business logic!
38. Seen in a project evaluation 38
39. Consider This API Usability over API RESTfulness and Scenarios first, formatting second 39
40. Standardisation JSON-API
 http://jsonapi.org HAL http://stateless.co/hal_specification.html 40
41. 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
42. Some Myths Debunked 42
43. Myth 1 I don’t know how my API will be used 43
44. Myth 2 If my features change, my entire API must change 44
45. Thank you! Questions? http://www.egeniq.com info@egeniq.com @egeniq http://www.egeniq.com ivo@egeniq.com @ijansch