http://www.egeniq.com [email protected] @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 

About Me @ijansch Entreprenerd Mobile & Web Developer Author & Speaker http://joind.in/8456 2 

About Egeniq Mobile Development Knowledge Distributed 3 

Unfortunately most people don’t read beyond: VERBS Get, Post, Put, Delete RESOURCES The stuff you work with. 4 The Problem with REST 

Resources, like bacon 5 POST /bacon GET /bacon PUT /bacon DELETE /bacon 

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

REST API (ZF based) Their design 7 SQL database Models Controllers Views /orders /products /orders/:id/products /products/:id etc 

Website (ZF/YUI based) REST API (ZF based) The design 8 SQL database Models Controllers Views API client Models Controllers Views 

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 

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

WTF “No. I can not fix your performance problem” 11 

Website (ZF/YUI based) REST API (ZF based) Problem 1 12 SQL database Models Controllers Views API client Models Controllers Views 1x 26x 

Website REST API Problem 2 13 SQL database THIN BUSINESS LOGIC Controllers Views API client THICK BUSINESS LOGIC Controllers Views 

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

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

Website REST API Problem 3 16 SQL database THIN BUSINESS LOGIC Controllers Views API client THICK BUSINESS LOGIC Controllers Views Mobile Client? 

Important REST is NOT an excuse to expose your raw data model 17 

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

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 

It doesn’t have to end this way Just think the API through 20 

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 

Teach by example: Pathé Thuis 22 Zombies 

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

Scenarios ‣Order a movie ‣Watch a movie ‣See list of my movies ‣See what’s available 24 

Scenario: view available movies 25 My zombie movies Featured movies Featured movie collections Recommendations Popular movies 

Would this work? ‣GET /movies/:id ‣GET /tickets ‣GET /users/:id 26 

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 

Fat resources { "promoslots": [{ "position": "home", "movies": [{ "id": 1012, "title": "Zombie Apocalypse", ... },{ "id": 1020, "title": "Zombie Reloaded”, ... }] }] } 28 

Compound resources { "promoslots": [{ "position": "home", "movies": [1012,1024,942] }], "movies": [{ "id": 1012, "title": "Zombie Apocalypse", ... }] } 29 

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 

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 

Standardisation http://jsonapi.org 32 

Client REST API Approach, visualised 33 SQL database BUSINESS LOGIC Controllers Views API client Controllers Views Look mum, no business logic! 

Creating Scenario Driven APIs Or at least how we do it 34 

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 

Create resource map 36 

Create resource map 37 

Generate rewrite rules 38 

Write controllers 39 

Documentation generation ‣Using Mike van Riel’s phpDocumentor tools 40 

‣Also using Mike’s phpDocumentor tools API validation 41 

The best way to eat the elephant standing in your path is to cut it up into little pieces African Proverb 42 

Myth 1 I don’t know how my API will be used 43 

Myth 2 If my features change, my entire API must change 44 

Myth 3 This talk is an anti REST talk 45 

Remember YOU ARE NOT (unless you are) 46 

Thank you! Questions? http://www.egeniq.com [email protected] @egeniq http://www.egeniq.com [email protected] @ijansch http://joind.in/8456 

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