Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Scenario Driven API Design (Apidays Paris)

B272216b76be8aacbfd11fad48196558?s=47 Ivo Jansch
December 02, 2014

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.

B272216b76be8aacbfd11fad48196558?s=128

Ivo Jansch

December 02, 2014
Tweet

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