'Scenario Driven Design' allow programmers to make more usable APIs and avoid performance issues. REST principles are often misunderstood and programmers expose their raw data model without any logic. Think about your scenarios first !

1. MAXIME LEMAITRE – 18/6/2015
Scenario Driven Design
… Yet another Blabla Driven Design …

2. Agenda
• Inspirations
• The dashboard problem
• Introducing Scenario Driven design
• Examples
– VOD
– Twitter
– Office for Ipad
– “Betclic”
• Conclusion

3. Inspirations
Scenario Driven API Design
Or: how to make more usable APIs
By Ivo Jansch (APIDays, Paris)

4. … a long time ago …
Our page is so slow to load
can you fix the performance problem ?

5. • The design
– /orders
– /orders/:id
– /orders/:id/details
– /products
– /products/:id
– …
5
The basic design
“A Home page 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” … What about performance ?
26 API Calls !!
“But our API is so RESTfull !”
What’s the problem ?

6. What’s the problem ?
What is a REST resource ?
Is you raw data model ?
Where is the Business logic ?
Where it should be ?
What if you need to release a new client ? (WebApp, Mobile, …)

7. What’s the problem² ?
• This is not a REST problem
– REST is a great way to expose data
• But…
– REST is not an excuse to expose your raw data model
– REST is not an excuse to stop thinking about business logic
“Smart Data & dumb code works a lot better
than the other way around“
The Cathedral & The Bazaar, Eric S. Raymond
 Smart APIs, dump clients
Note : Batch requests could help, but business logic is still on client side...

8. Introducing ‘Scenario Driven API Design’

9. Introducing 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.
Reminders :
• Data Driven Design
 from Data to generic clients
• Client Driven Design
 from Specific clients to data

10. Typical VOD features

11. Scenario Driven Design Approach
• 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.

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

13. Scenario Driven Design
(1) ‘Home’ screen
(4) /promoslots/home
(2) Promote content to the home
screen
(3) Movies, collections, banners,

14. Interface Design
• Exemples
– /recommendations
• or /users/@me/recommendations
– /promoslots/:screen
– /users/@me/movies
– /users/@me/movies/liked
– /movies
• Consider scenario’s at the highest level
– Business Logic entirely API side
– Important: find balance between generic and specific

15. Framework Design
Framework Design Guidelines: Conventions, Idioms,
and Patterns for Reusable .NET Libraries
by Krzysztof Cwalina & Brad Abrams
” Frameworks often contain a very large set of
APIs. This enables advanced scenarios that require
power and expressiveness. However, most
development revolves around a small set of
common scenarios that use a relatively small
subset of the full framework. To optimize the
overall productivity of the developers using a
framework, it is crucial to invest heavily in the
design of APIs that are used in the most common
scenarios.”

16. Do & Don’t
http://blogs.msdn.com/b/kcwalina/archive/2005/05/05/scenariodrivendesign.aspx
• Do make sure that the API design specification is the central part of
the design of any feature that includes a publicly accessible API.
• Do define top usage scenarios for each major feature area.
• Do ensure that the scenarios correspond to appropriate abstraction
level. They should roughly correspond to the end user use cases.
• Do design APIs by first writing code samples for the main scenarios
and then defining the object model to support the code samples.
• Do not rely solely on standard design methodologies (for example
UML) when designing the public APIs layer of a framework.
• Do not start API design with object model diagrams.
• Do organize usability studies to test APIs in main scenarios.

17. Examples

18. The example of Twitter API
• The Twitter API exposes many methods for tweets, favorites, retweets, followers,
search, …
• What is the most common feature of twitter ? => Timelines
• The home timeline is central to how most users interact with the Twitter service.
Do no try to reinvent the wheel
Dumb clients, Smart APIs

19. Office for Ipad
“designed for iPad” as opposed to “ported to iPad
• Several key mobile scenarios
– Packing up for the ride home
– Starting from scratch
– Last minute scramble
– Buttoning things up
– Collaborating with coworkers
– Taking notes
• “bringing over hundreds of
Office commands, toolbars,
and dialogs to the iPad would
be, simply put, a mistake.”

20. Conclusion
- Better Usability
- Better Performance
- Better maintainability
- Less duplicates

21. Questions

22. References
• http://blogs.msdn.com/b/kcwalina/archive/2005/05/05/scenariodrivendesign.asp
x
• https://speakerdeck.com/ijansch/scenario-driven-api-design-apidays-paris
• https://speakerdeck.com/ijansch/scenario-driven-api-design
• https://github.com/dotnet/corefx/wiki/Framework-Design-Guidelines-Digest
• http://www.slideshare.net/clintedmonson/advanced-oop-laws-principles-idioms-
presentation?qid=63cb2104-5ac7-48e9-b3eb-
aebf85cf7459&v=qf1&b=&from_search=1
• http://www.streetinsider.com/Insiders+Blog/Microsoft+%28MSFT%29+Shows+Ho
w+Office+for+iPad+was+Designed/9519656.html