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.

Transcript

1. http://www.egeniq.com
   info@egeniq.com
   @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
   

   View Slide

2. About Me
   @ijansch
   Entreprenerd
   Mobile & Web Developer
   Author & Speaker
   http://joind.in/8456
   2
   

   View Slide

3. About Egeniq
   Mobile
   Development
   Knowledge
   Distributed
   3
   

   View Slide

4. Unfortunately most people don’t read beyond:
   VERBS
   Get, Post, Put, Delete
   RESOURCES
   The stuff you work with.
   4
   The Problem with REST
   

   View Slide

5. Resources, like bacon
   5
   POST /bacon GET /bacon
   PUT /bacon DELETE /bacon
   

   View Slide

6. A few months ago:
   “We have some issues.
   Can you fix our
   performance problem?”
   6
   An interesting, anonymous case
   

   View Slide

7. REST API (ZF based)
   Their design
   7
   SQL database
   Models
   Controllers Views
   /orders
   /products
   /orders/:id/products
   /products/:id
   etc
   

   View Slide

8. Website (ZF/YUI based)
   REST API (ZF based)
   The design
   8
   SQL database
   Models
   Controllers Views
   API client
   Models
   Controllers Views
   

   View Slide

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
   

   View Slide

10. What did a trace show?
    1 dashboard page
    26
    API calls
    124 objects passed between api and client
    10
    

    View Slide

11. WTF
    “No. I can not fix your performance problem”
    11
    

    View Slide

12. Website (ZF/YUI based)
    REST API (ZF based)
    Problem 1
    12
    SQL database
    Models
    Controllers Views
    API client
    Models
    Controllers Views
    1x
    26x
    

    View Slide

13. Website
    REST API
    Problem 2
    13
    SQL database
    THIN BUSINESS LOGIC
    Controllers Views
    API client
    THICK BUSINESS LOGIC
    Controllers Views
    

    View Slide

14. Something went terribly wrong
    14
    SELECT * FROM order WHERE id = 2
    orderBean.selectById(2)
    $orderModel->getOrder(2)
    http://api/orders/2
    RESTful APIs
    

    View Slide

15. OMG
    Give the monkey a screwdriver.
    Prepare to get hurt.
    15
    

    View Slide

16. Website
    REST API
    Problem 3
    16
    SQL database
    THIN BUSINESS LOGIC
    Controllers Views
    API client
    THICK BUSINESS LOGIC
    Controllers Views
    Mobile
    Client?
    

    View Slide

17. Important
    REST is NOT an excuse
    to expose your raw data model
    17
    

    View Slide

18. Important
    REST is NOT an excuse
    to stop thinking about business logic
    18
    

    View Slide

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
    

    View Slide

20. It doesn’t have to end this way
    Just think the API through
    20
    

    View Slide

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
    

    View Slide

22. Teach by example: Pathé Thuis
    22
    Zombies
    

    View Slide

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

    View Slide

24. Scenarios
    ‣Order a movie
    ‣Watch a movie
    ‣See list of my movies
    ‣See what’s available
    24
    

    View Slide

25. Scenario: view available movies
    25
    My zombie movies
    Featured movies
    Featured movie collections
    Recommendations
    Popular movies
    

    View Slide

26. Would this work?
    ‣GET /movies/:id
    ‣GET /tickets
    ‣GET /users/:id
    26
    

    View Slide

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
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

32. Standardisation
    http://jsonapi.org
    32
    

    View Slide

33. Client
    REST API
    Approach, visualised
    33
    SQL database
    BUSINESS LOGIC
    Controllers Views
    API client
    Controllers Views
    Look mum, no business logic!
    

    View Slide

34. Creating Scenario Driven APIs
    Or at least how we do it
    34
    

    View Slide

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
    

    View Slide

36. Create resource map
    36
    

    View Slide

37. Create resource map
    37
    

    View Slide

38. Generate rewrite rules
    38
    

    View Slide

39. Write controllers
    39
    

    View Slide

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

    View Slide

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

    View Slide

42. The best way to eat the
    elephant standing in your path
    is to cut it up into little pieces
    African Proverb
    42
    

    View Slide

43. Myth 1
    I don’t know how
    my API will be used
    43
    

    View Slide

44. Myth 2
    If my features change,
    my entire API must change
    44
    

    View Slide

45. Myth 3
    This talk is an anti REST talk
    45
    

    View Slide

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

    View Slide

47. Thank you! Questions?
    http://www.egeniq.com
    info@egeniq.com
    @egeniq
    http://www.egeniq.com
    ivo@egeniq.com
    @ijansch
    http://joind.in/8456
    

    View Slide

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

    View Slide