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 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
    [email protected]
    @egeniq
    http://www.egeniq.com
    [email protected]
    @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/
    [email protected]/4612278861
    ‣ ’3 pounds of goodness’ by Robert S. Donovan - http://www.flickr.com/photos/
    [email protected]/7997980826
    ‣ ‘Eating the bacon’ by Beatrice Murch - http://www.flickr.com/photos/
    [email protected]/5070496311
    ‣ ‘David Zuelke’ by Sebastian Bergmann - http://www.flickr.com/photos/
    [email protected]/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/
    [email protected]/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