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

Scenario Driven API Design

Scenario Driven API Design

We work a lot with APIs and often encounter very badly designed APIs. Claiming that it's RESTful, such APIs often directly expose an underlying data model and skip the design part. This is not a REST problem, but a problem of not understanding REST. In this talk, I presented an approach to get to APIs that are more usable and that have a better design. Presented at the Dutch PHP Conference 2013.


Ivo Jansch

June 08, 2013


  1. @egeniq Dutch PHP Conference, June 8, 2013 Ivo

    Jansch Scenario Driven API Design Or: the one with rants about REST Or: the one with Zombies, Coffee, Beer, Elephpants & Bacon
  2. About Me @ijansch Entreprenerd Mobile & Web Developer Author &

    Speaker 2
  3. About Egeniq Mobile Development Knowledge Distributed 3

  4. Unfortunately most people don’t read beyond: VERBS Get, Post, Put,

    Delete RESOURCES The stuff you work with. 4 The Problem with REST
  5. Resources, like bacon 5 POST /bacon GET /bacon PUT /bacon

    DELETE /bacon
  6. A few months ago: “We have some issues. Can you

    fix our performance problem?” 6 An interesting, anonymous case
  7. REST API (ZF based) Their design 7 SQL database Models

    Controllers Views /orders /products /orders/:id/products /products/:id etc
  8. Website (ZF/YUI based) REST API (ZF based) The design 8

    SQL database Models Controllers Views API client Models Controllers Views
  9. The feature “A dashboard showing the user’s open orders, the

    order status, one product for each order plus the thumb, and a list of the last 5 sent orders” Order: 12314 Dispatched Zombie King 9
  10. What did a trace show? 1 dashboard page 26 API

    calls 124 objects passed between api and client 10
  11. WTF “No. I can not fix your performance problem” 11

  12. Website (ZF/YUI based) REST API (ZF based) Problem 1 12

    SQL database Models Controllers Views API client Models Controllers Views 1x 26x
  13. Website REST API Problem 2 13 SQL database THIN BUSINESS

    LOGIC Controllers Views API client THICK BUSINESS LOGIC Controllers Views
  14. Something went terribly wrong 14 SELECT * FROM order WHERE

    id = 2 orderBean.selectById(2) $orderModel->getOrder(2) http://api/orders/2 RESTful APIs
  15. OMG Give the monkey a screwdriver. Prepare to get hurt.

  16. Website REST API Problem 3 16 SQL database THIN BUSINESS

    LOGIC Controllers Views API client THICK BUSINESS LOGIC Controllers Views Mobile Client?
  17. Important REST is NOT an excuse to expose your raw

    data model 17
  18. Important REST is NOT an excuse to stop thinking about

    business logic 18
  19. Very Important REST IS NOT THE PROBLEM. YOU ARE. (well,

    at least if you’re the dude that coded that API from the anonymous example) (Yes, I know who you are) 19
  20. It doesn’t have to end this way Just think the

    API through 20
  21. Scenario Driven Design ‣How is your API going to be

    used ‣Usage scenarios ‣Don’t call it REST if that’s too scary • HTTP API, JSON API, ... 21
  22. Teach by example: Pathé Thuis 22 Zombies

  23. Big ecosystem, lots of clients 23 API ipad tv web

    xbox android ???
  24. Scenarios ‣Order a movie ‣Watch a movie ‣See list of

    my movies ‣See what’s available 24
  25. Scenario: view available movies 25 My zombie movies Featured movies

    Featured movie collections Recommendations Popular movies
  26. Would this work? ‣GET /movies/:id ‣GET /tickets ‣GET /users/:id 26

  27. This would work better: ‣/recommendations • or /users/@me/recommendations ‣/promoslots ‣/users/@me/movies

    ‣/users/@me/movies/liked 27 Interesting concept: Pseudo identifiers compound resources views
  28. Fat resources { "promoslots": [{ "position": "home", "movies": [{ "id":

    1012, "title": "Zombie Apocalypse", ... },{ "id": 1020, "title": "Zombie Reloaded”, ... }] }] } 28
  29. Compound resources { "promoslots": [{ "position": "home", "movies": [1012,1024,942] }],

    "movies": [{ "id": 1012, "title": "Zombie Apocalypse", ... }] } 29
  30. Smart responses { "total": 100, "count": 10, "promoslots": [{ "position":

    "home", "movies": [{ "id": 1012, "href": "" "title": "Zombie Apocalypse", ... },{ "id": 1020, "href": "" "title": "Zombie Reloaded”, ... }] }] } 30
  31. Actions for clarity ‣If you don’t have enough verbs ‣If

    you don’t like • ‘POST /users/@me/movies/1012/likes’ ‣CHEAT: • /movies/1012/;like • /movies/1012/;unlike (but don’t tell @dzuelke) 31
  32. Standardisation 32

  33. Client REST API Approach, visualised 33 SQL database BUSINESS LOGIC

    Controllers Views API client Controllers Views Look mum, no business logic!
  34. Creating Scenario Driven APIs Or at least how we do

    it 34
  35. Our approach to API designs ‣Research usage scenarios ‣Create resource

    map ‣Generate rewrite rules ‣Use Zend MVC • without dynamic routing • with lightweight Zend_Application • (With Symfony DI by the way) ‣Validate API 35
  36. Create resource map 36

  37. Create resource map 37

  38. Generate rewrite rules 38

  39. Write controllers 39

  40. Documentation generation ‣Using Mike van Riel’s phpDocumentor tools 40

  41. ‣Also using Mike’s phpDocumentor tools API validation 41

  42. The best way to eat the elephant standing in your

    path is to cut it up into little pieces African Proverb 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. Myth 3 This talk is an anti REST talk 45

  46. Remember YOU ARE NOT (unless you are) 46

  47. Thank you! Questions? @egeniq @ijansch

  48. Credits ‣ ‘Mom, willie took my teat again’ by Woodlywonderworks

    - photos/wwworks/275200442 ‣ ‘Bacon in the oven’ by Joel Kramer - 75001512@N00/4612278861 ‣ ’3 pounds of goodness’ by Robert S. Donovan - 10687935@N04/7997980826 ‣ ‘Eating the bacon’ by Beatrice Murch - 82439748@N00/5070496311 ‣ ‘David Zuelke’ by Sebastian Bergmann - 90237600@N00/4065324036 ‣ ‘ElePHPants’ by Sebastian Bergmann - sebastian_bergmann/2338238596/ ‣ ‘Beer candles from Ghent’ by Guy Renard - 72116883@N00/6933441530 ‣ ‘Nein nein nein das ist verboten’ slide by Davis Zuelke - http:// drupalconmunich2012_http_rest_0.pdf