Scenario Driven API Design (Apidays Paris)

In this talk we will look at an approach to API design that I have been practicing and refining for the past couple of years. We will look at what Scenario Driven Design means, when it is useful, and what the advantages and disadvantages are, when comparing this design approach with other API design methodologies. We will see how it will aid developers that need to create APIs for a large range of devices and offer advice on how to create APIs that are useful and usable.

Transcript

1. http://www.egeniq.com
   info@egeniq.com
   @egeniq
   APIDays Paris, December 2, 2014
   Ivo Jansch
   Scenario Driven API Design
   Or: how to make more usable APIs
   

   View Slide

2. About Me
   @ijansch
   Entreprenerd
   (@egeniq / @buildozerapp)
   App & Api Developer
   Author & Speaker
   Upcoming: 

   http://leanpub.com/nways
   Conference Organizer
   (@endpointcon / @mdevcon)
   2
   

   View Slide

3. About Egeniq
   Apps & Apis
   for clients
   3
   

   View Slide

4. About Buildozer
   4
   Checkout Validation Distribution
   Code
   Buildozer
   http://buildozer.io
   Continuous Integration for apps
   

   View Slide

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

   View Slide

6. REST API (PHP)
   Their design
   6
   SQL database
   Models
   Controllers Views
   /orders
   /products
   /orders/:id/products
   /products/:id
   etc
   

   View Slide

7. Website (YUI)
   REST API (PHP)
   The design
   7
   SQL database
   Models
   Controllers Views
   API client
   Models
   Controllers Views
   

   View Slide

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

   View Slide

9. WTF
   “No. I can not fix your performance problem”
   “But, but.. our API is so RESTful!”
   9
   

   View Slide

10. Website (YUI based)
    REST API (PHP based)
    Problem
    10
    SQL database
    Models
    Controllers Views
    API client
    Models
    Controllers Views
    1x
    26x
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

14. Website
    REST API
    What if we add even more clients?
    14
    SQL database
    THIN BUSINESS LOGIC
    Controllers Views
    API client
    THICK BUSINESS LOGIC
    Controllers Views
    Mobile
    Client?
    

    View Slide

15. Important
    This is not a REST problem.
    REST is a great way to expose an API.
    15
    

    View Slide

16. Important
    However:
    REST is NOT an excuse
    to expose your raw data model
    16
    

    View Slide

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

    View Slide

18. Introducing ‘Scenario Driven API Design’
    18
    

    View Slide

19. Data Driven Design
    19
    Data Modeling
    API interface (REST/HAL/..)
    Generic Clients
    

    View Slide

20. Client Driven Design
    20
    Data Modeling
    API interface (REST/HAL/..)
    Specific Clients
    

    View Slide

21. Scenario Driven Design
    21
    Data Modeling
    Interface Design
    Specific/Generic Clients
    Service Design
    

    View Slide

22. Scenario Driven Design
    ‣1. Client analysis
    ‣Identify client needs
    ‣Usage scenarios
    ‣2. Service design
    ‣Optimal ways to service the client scenarios
    ‣3. Data modelling
    ‣Create data model to support the scenario’s
    ‣Low level and high level concepts
    ‣4. Interface design
    ‣REST/HAL etc. interface
    ‣Versioning, etc.
    22
    

    View Slide

23. Teach by example: Pathé Thuis
    23
    

    View Slide

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

    View Slide

25. Typical VOD features
    25
    My rented movies
    Featured movies
    Featured movie collections
    Recommendations
    Popular movies
    

    View Slide

26. Would this work?
    ‣Data Driven:
    ‣GET /movies/:id
    ‣GET /tickets
    ‣GET /users/:id
    ‣Yes it would work
    ‣but we would easily get stuck with the ’26 api calls’
    problem
    26
    

    View Slide

27. Scenario Driven Design
    ‣Identify all relevant scenarios:
    ‣Order a movie
    ‣Watch a movie
    ‣See list of my movies
    ‣Promote content on the home screen
    ‣See what’s available
    ‣Like/unlike movies
    ‣Interactions are platform-specific, scenarios
    usually aren’t.
    27
    

    View Slide

28. “Promote content on the home page”
    ‣All clients should present, on their home
    screen, after login:
    ‣The user’s most recently rented movies
    ‣User specific recommendations
    ‣Movie top 20
    ‣Featured movies
    28
    

    View Slide

29. Scenario Driven Design
    29
    Data Modeling
    API interface
    Specific/Generic
    Clients
    Service Design
    1. ’home’ screen
    

    View Slide

30. Scenario Driven Design
    30
    Data Modeling
    API interface
    Specific/Generic
    Clients
    Service Design 2. Promote content on
    the home screen
    1. ’home’ screen
    

    View Slide

31. Scenario Driven Design
    31
    Movie
    Banner
    Promoslot
    Collection
    Screen
    (home, profile)
    Purchase
    

    View Slide

32. Scenario Driven Design
    32
    Data Modeling
    API interface
    Specific/Generic
    Clients
    Service Design 2. Promote content on
    the home screen
    3. Movies, collections, banners
    1. ’home’ screen
    

    View Slide

33. Scenario Driven Design
    33
    Data Modeling
    API interface
    Specific/Generic
    Clients
    Service Design 2. Promote content on
    the home screen
    3. Movies, collections, banners
    4. /promoslots/home
    1. ’home’ screen
    

    View Slide

34. The interface
    ‣/recommendations
    • or /users/@me/recommendations
    ‣/promoslots/:screen
    ‣/users/@me/movies
    ‣/users/@me/movies/liked
    ‣/movies
    34
    Interesting concept: Pseudo identifiers
    compound resources
    views
    

    View Slide

35. Consider scenario’s at the highest level
    ‣GET /users/@me/dashboard
    ‣High Level Scenario
    ‣Business Logic entirely API side
    ‣Important: find balance between generic
    and specific
    35
    

    View Slide

36. Wise Words
    ‣Eric S. Raymond: “Smart data and dumb
    code works a lot better than the other way
    around” (from: The Cathedral & The
    Bazaar)
    ‣In 2014 this means: 

    

    Smart APIs, dumb clients
    36
    

    View Slide

37. Client
    REST API
    Business Logic where it belongs
    37
    Data
    BUSINESS LOGIC
    Controllers Views
    API client
    Controllers Views
    Look mum, no business logic!
    

    View Slide

38. Seen in a project evaluation
    38
    

    View Slide

39. Consider This
    API Usability over API RESTfulness
    and
    Scenarios first, formatting second
    39
    

    View Slide

40. Standardisation
    JSON-API

    http://jsonapi.org
    HAL
    http://stateless.co/hal_specification.html
    40
    

    View Slide

41. A word about tool vendors
    41
    Data Modeling
    Interface Design
    Specific/Generic Clients
    Service Design
    db vendor space
    (commoditised
    ~ 16 years ago)
    api tool vendor space
    (to be commoditised)
    you
    

    View Slide

42. Some Myths Debunked
    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. Thank you! Questions?
    http://www.egeniq.com
    info@egeniq.com
    @egeniq
    http://www.egeniq.com
    ivo@egeniq.com
    @ijansch
    

    View Slide