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

Scenario Driven API Design - Zendcon Edition

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.

Ivo Jansch

November 19, 2013
Tweet

More Decks by Ivo Jansch

Other Decks in Technology

Transcript

  1. http://www.egeniq.com
    [email protected]
    @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 full-size slide

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

    View full-size slide

  3. About Egeniq
    Mobile
    Development
    Knowledge
    Distributed
    !
    !
    !
    !
    !
    !
    !3

    View full-size 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 full-size slide

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

    View full-size slide

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

    View full-size slide

  7. REST API (ZF based)
    Their design
    !7
    SQL database
    Models
    Controllers Views
    /orders

    /products

    /orders/:id/products

    /products/:id

    etc

    View full-size slide

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

    View full-size 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 full-size slide

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

    View full-size slide

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

    View full-size 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 full-size slide

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

    View full-size 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 full-size slide

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

    View full-size 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 full-size slide

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

    View full-size slide

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

    View full-size 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 full-size slide

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

    View full-size 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 full-size slide

  22. Teach by example: Pathé Thuis
    !22
    Zombies

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size 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 full-size 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 full-size slide

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

    View full-size slide

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

    View full-size 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 full-size slide

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

    View full-size slide

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

    View full-size slide

  34. Fat resources
    {
    "promoslots": [{

    "position": "home",

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

    "id": 1020,

    "title": "Zombie Reloaded”,

    ...

    }]
    }]
    }
    !34

    View full-size slide

  35. Compound resources
    {
    "promoslots": [{

    "position": "home",

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

    View full-size 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 full-size 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 full-size slide

  38. Standardisation
    JSON-API

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

    View full-size slide

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

    View full-size 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 full-size slide

  41. Create resource map
    !41

    View full-size slide

  42. Create resource map
    !42

    View full-size slide

  43. Generate rewrite rules
    !43

    View full-size slide

  44. Write controllers
    !44

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  53. Thank you! Questions?
    http://www.egeniq.com
    [email protected]
    @egeniq
    http://www.egeniq.com
    [email protected]
    @ijansch
    http://joind.in/9265

    View full-size 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 full-size slide