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.

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
   

   View Slide

2. About Me
   @ijansch
   Entreprenerd
   Mobile & Web Developer
   Author & Speaker
   !
   http://joind.in/9265
   !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 (yet) 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. 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
    

    View Slide

29. All clients must implement this feature
    !29
    API
    ipad tv web xbox
    android ???
    

    View Slide

30. Ergo:
    ‣GET /users/@me/dashboard
    !
    !
    ‣High Level Scenario
    ‣Business Logic entirely API side
    !30
    

    View Slide

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
    

    View Slide

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

    View Slide

33. Consider This
    API Usability over API RESTfulness
    !
    or
    !
    Scenarios first, formatting second
    !33
    

    View Slide

34. Fat resources
    {
    "promoslots": [{

    "position": "home",

    "movies": [{
    "id": 1012,
    "title": "Zombie Apocalypse",
    ...
    },{

    "id": 1020,

    "title": "Zombie Reloaded”,

    ...

    }]
    }]
    }
    !34
    

    View Slide

35. Compound resources
    {
    "promoslots": [{

    "position": "home",

    "movies": [1012,1024,942]
    }],
    "movies": [{
    "id": 1012,
    "title": "Zombie Apocalypse",
    ...
    }]
    }
    !35
    

    View Slide

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
    

    View Slide

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
    

    View Slide

38. Standardisation
    JSON-API

    http://jsonapi.org
    !
    !
    HAL
    http://stateless.co/hal_specification.html
    !38
    

    View Slide

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

    View Slide

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
    

    View Slide

41. Create resource map
    !41
    

    View Slide

42. Create resource map
    !42
    

    View Slide

43. Generate rewrite rules
    !43
    

    View Slide

44. Write controllers
    !44
    

    View Slide

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

    View Slide

46. ‣Also using Mike’s phpDocumentor tools
    !
    !
    !
    !
    !
    !
    !
    API validation
    !46
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide