Save 37% off PRO during our Black Friday Sale! »

Scenario Driven API Design (CodeByTheSea)

B272216b76be8aacbfd11fad48196558?s=47 Ivo Jansch
November 03, 2015

Scenario Driven API Design (CodeByTheSea)

Presented at Code By The Sea on November 3, 2015

B272216b76be8aacbfd11fad48196558?s=128

Ivo Jansch

November 03, 2015
Tweet

Transcript

  1. http://www.egeniq.com info@egeniq.com @egeniq Code By The Sea November 3, 2015

    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 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 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
  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 2015 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