Scenario Driven API Design

We work a lot with APIs and often encounter very badly designed APIs. Claiming that it's RESTful, such APIs often directly expose an underlying data model and skip the design part. This is not a REST problem, but a problem of not understanding REST. In this talk, I presented an approach to get to APIs that are more usable and that have a better design. Presented at the Dutch PHP Conference 2013.

Transcript

1. http://www.egeniq.com info@egeniq.com @egeniq Dutch PHP Conference, June 8, 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/8456 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 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. Fat resources { "promoslots": [{ "position": "home", "movies": [{ "id": 1012, "title": "Zombie Apocalypse", ... },{ "id": 1020, "title": "Zombie Reloaded”, ... }] }] } 28
29. Compound resources { "promoslots": [{ "position": "home", "movies": [1012,1024,942] }], "movies": [{ "id": 1012, "title": "Zombie Apocalypse", ... }] } 29
30. 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”, ... }] }] } 30
31. 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) 31
32. Standardisation http://jsonapi.org 32
33. Client REST API Approach, visualised 33 SQL database BUSINESS LOGIC Controllers Views API client Controllers Views Look mum, no business logic!
34. Creating Scenario Driven APIs Or at least how we do it 34
35. 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 35
36. Create resource map 36
37. Create resource map 37
38. Generate rewrite rules 38
39. Write controllers 39
40. Documentation generation ‣Using Mike van Riel’s phpDocumentor tools 40
41. ‣Also using Mike’s phpDocumentor tools API validation 41
42. The best way to eat the elephant standing in your path is to cut it up into little pieces African Proverb 42
43. Myth 1 I don’t know how my API will be used 43
44. Myth 2 If my features change, my entire API must change 44
45. Myth 3 This talk is an anti REST talk 45
46. Remember YOU ARE NOT (unless you are) 46
47. Thank you! Questions? http://www.egeniq.com info@egeniq.com @egeniq http://www.egeniq.com ivo@egeniq.com @ijansch http://joind.in/8456
48. 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