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
2. About Me @ijansch Entreprenerd Mobile & Web Developer Author & Speaker ! http://joind.in/9265 !2
3. About Egeniq Mobile Development Knowledge Distributed ! ! ! ! ! ! !3
4. Unfortunately most people don’t read beyond: ! VERBS Get, Post, Put, Delete ! RESOURCES The stuff you work with. !4 The Problem with REST
5. Resources, like bacon !5 POST /bacon GET /bacon PUT /bacon DELETE /bacon
6. A few months ago: ! “We have some issues. Can you fix our performance problem?” !6 An interesting, anonymous case
7. REST API (ZF based) Their design !7 SQL database Models Controllers Views /orders /products /orders/:id/products /products/:id etc
8. Website (ZF/YUI based) REST API (ZF based) The design !8 SQL database Models Controllers Views API client Models Controllers Views
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
10. What did a trace show? 1 dashboard page ! 26 API calls ! 124 objects passed between api and client !10
11. WTF ! “No. I can not fix your performance problem” !11
12. Website (ZF/YUI based) REST API (ZF based) Problem 1 !12 SQL database Models Controllers Views API client Models Controllers Views 1x 26x
13. Website REST API Problem 2 !13 SQL database THIN BUSINESS LOGIC Controllers Views API client THICK BUSINESS LOGIC Controllers Views
14. Something went terribly wrong !14 SELECT * FROM order WHERE id = 2 orderBean.selectById(2) $orderModel->getOrder(2) http://api/orders/2 RESTful APIs
15. OMG ! Give the monkey a screwdriver. Prepare to get hurt. !15
16. Website REST API Problem 3 !16 SQL database THIN BUSINESS LOGIC Controllers Views API client THICK BUSINESS LOGIC Controllers Views Mobile Client?
17. Important REST is NOT an excuse to expose your raw data model !17
18. Important REST is NOT an excuse to stop thinking about business logic !18
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
20. It doesn’t have to end this way Just think the API through !20
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
22. Teach by example: Pathé Thuis !22 Zombies
23. Big ecosystem, lots of clients !23 API ipad tv web xbox android ???
24. Scenarios ‣Order a movie ‣Watch a movie ‣See list of my movies ‣See what’s available !24
25. Scenario: view available movies !25 My zombie movies Featured movies Featured movie collections Recommendations Popular movies
26. Would this work? ‣GET /movies/:id ‣GET /tickets ‣GET /users/:id !26
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
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
29. All clients must implement this feature !29 API ipad tv web xbox android ???
30. Ergo: ‣GET /users/@me/dashboard ! ! ‣High Level Scenario ‣Business Logic entirely API side !30
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
32. Client REST API Approach, visualised !32 SQL database BUSINESS LOGIC Controllers Views API client Controllers Views Look mum, no business logic!
33. Consider This API Usability over API RESTfulness ! or ! Scenarios first, formatting second !33
34. Fat resources { "promoslots": [{
 "position": "home",
 "movies": [{ "id": 1012, "title": "Zombie Apocalypse", ... },{
 "id": 1020,
 "title": "Zombie Reloaded”,
 ...
 }] }] } !34
35. Compound resources { "promoslots": [{
 "position": "home",
 "movies": [1012,1024,942] }], "movies": [{ "id": 1012, "title": "Zombie Apocalypse", ... }] } !35
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
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
38. Standardisation JSON-API
 http://jsonapi.org ! ! HAL http://stateless.co/hal_specification.html !38
39. Creating Scenario Driven APIs Or at least how we do it !39
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
41. Create resource map !41
42. Create resource map !42
43. Generate rewrite rules !43
44. Write controllers !44
45. Documentation generation ‣Using Mike van Riel’s phpDocumentor tools ! ! ! ! ! ! ! !45
46. ‣Also using Mike’s phpDocumentor tools ! ! ! ! ! ! ! API validation !46
47. Something you probably should look at ! ! http://apigility.org !47
48. The best way to eat the elephant standing in your path is to cut it up into little pieces African Proverb !48
49. Myth 1 I don’t know how my API will be used !49
50. Myth 2 If my features change, my entire API must change !50
51. Myth 3 This talk is an anti REST talk !51
52. Remember YOU ARE NOT ! ! ! (unless you are) !52
53. Thank you! Questions? http://www.egeniq.com info@egeniq.com @egeniq http://www.egeniq.com ivo@egeniq.com @ijansch http://joind.in/9265
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