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

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

More Decks by Ivo Jansch

Other Decks in Technology


  1. http://www.egeniq.com [email protected] @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. Unfortunately most people don’t read beyond: VERBS Get, Post, Put,

    Delete RESOURCES The stuff you work with. 4 The Problem with REST
  3. A few months ago: “We have some issues. Can you

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

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

    SQL database Models Controllers Views API client Models Controllers Views
  6. 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
  7. What did a trace show? 1 dashboard page 26 API

    calls 124 objects passed between api and client 10
  8. Website (ZF/YUI based) REST API (ZF based) Problem 1 12

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

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

    id = 2 orderBean.selectById(2) $orderModel->getOrder(2) http://api/orders/2 RESTful APIs
  11. Website REST API Problem 3 16 SQL database THIN BUSINESS

    LOGIC Controllers Views API client THICK BUSINESS LOGIC Controllers Views Mobile Client?
  12. 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
  13. 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
  14. Scenarios ‣Order a movie ‣Watch a movie ‣See list of

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

    Featured movie collections Recommendations Popular movies
  16. 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
  17. Fat resources { "promoslots": [{ "position": "home", "movies": [{ "id":

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

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

    "home", "movies": [{ "id": 1012, "href": "http://api.example.com/movies/1012" "title": "Zombie Apocalypse", ... },{ "id": 1020, "href": "http://api.example.com/movies/1020" "title": "Zombie Reloaded”, ... }] }] } 30
  20. 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
  21. Client REST API Approach, visualised 33 SQL database BUSINESS LOGIC

    Controllers Views API client Controllers Views Look mum, no business logic!
  22. 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
  23. The best way to eat the elephant standing in your

    path is to cut it up into little pieces African Proverb 42
  24. Credits ‣ ‘Mom, willie took my teat again’ by Woodlywonderworks

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