Scenario Driven API Design - Zendcon Edition

B272216b76be8aacbfd11fad48196558?s=47 Ivo Jansch
November 19, 2013

Scenario Driven API Design - Zendcon Edition

A talk on Scenario Driven API Design, discussing why it's important to think about your APIs and how to avoid the pitfall of creating APIs without any business logic, exposing your raw data models.

Delivered at Zendcon Europe.

B272216b76be8aacbfd11fad48196558?s=128

Ivo Jansch

November 19, 2013
Tweet

Transcript

  1. http://www.egeniq.com info@egeniq.com @egeniq Zendcon Europe, November 19, 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 ! http://joind.in/9265 !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. !15
  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 (yet) 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. Consider the scenario again ‣All clients should present, on their

    home screen, after login: ‣The user’s 3 most recently rented movies ‣User specific recommendations ‣Movie top 20 ‣Featured movies !28
  29. All clients must implement this feature !29 API ipad tv

    web xbox android ???
  30. Ergo: ‣GET /users/@me/dashboard ! ! ‣High Level Scenario ‣Business Logic

    entirely API side !30
  31. Ergo: ‣Eric S. Raymond: “Smart data and dumb code works

    a lot better than the other way around” (from: The Cathedral & The Bazaar) ! ‣In 2013 this means: 
 
 Smart APIs, dumb clients !31
  32. Client REST API Approach, visualised !32 SQL database BUSINESS LOGIC

    Controllers Views API client Controllers Views Look mum, no business logic!
  33. Consider This API Usability over API RESTfulness ! or !

    Scenarios first, formatting second !33
  34. Fat resources { "promoslots": [{
 "position": "home",
 "movies": [{ "id":

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

    "movies": [{ "id": 1012, "title": "Zombie Apocalypse", ... }] } !35
  36. 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”,
 ...
 }] }] } !36
  37. 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) !37
  38. Standardisation JSON-API
 http://jsonapi.org ! ! HAL http://stateless.co/hal_specification.html !38

  39. Creating Scenario Driven APIs Or at least how we do

    it !39
  40. 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 !40
  41. Create resource map !41

  42. Create resource map !42

  43. Generate rewrite rules !43

  44. Write controllers !44

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

    ! ! ! ! ! !45
  46. ‣Also using Mike’s phpDocumentor tools ! ! ! ! !

    ! ! API validation !46
  47. Something you probably should look at ! ! http://apigility.org !47

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

    path is to cut it up into little pieces African Proverb !48
  49. Myth 1 I don’t know how my API will be

    used !49
  50. Myth 2 If my features change, my entire API must

    change !50
  51. Myth 3 This talk is an anti REST talk !51

  52. Remember YOU ARE NOT ! ! ! (unless you are)

    !52
  53. Thank you! Questions? http://www.egeniq.com info@egeniq.com @egeniq http://www.egeniq.com ivo@egeniq.com @ijansch http://joind.in/9265

  54. 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