Building an API

Following the process of a request in, around, and back out of an example API learning best practices along the way.

Transcript

1. Building an API Lessons learned six months in
2. Steven Wade Senior Software Engineer at Fuel Founder/Organizer of UpstatePHP
3. What We’ll Cover Following the Request to Response path: • Resources • RESTful Routing • Input Types • Response Formats • Response Codes
4. What We Won’t Cover • Validation • Authentication (recommend OAuth2) • Versioning
5. Resources If REST is about verbs, Resources are the nouns.
6. Resource Naming Think of the base form of each “entity” /tabby-cats (not preferred) /cats (preferred)
7. Resource Naming Think of the base form of each “entity” /tabby-cats (not preferred) /cats?type=tabby (preferred)
8. Resource Naming Best to keep it plural
9. GET /cats GET /cat/1234 POST /cat
10. GET /people GET /person/1234 POST /person
11. GET /people GET /people/1234 POST /people
12. *wife said my presentation was too boring * Let’s build something!
13. Sample Application • PHP 5.4 • PostgreSQL 9.3 • Laravel 4.2 (Eloquent FTW!)
14. OpenUpstate API (imaginary) Resources: • Organizations • Members • Events • Venues
15. RESTful Routing • CONNECT • DELETE • GET • HEAD • OPTIONS • PATCH • POST • PUT • TRACE
16. RESTful Routing • CONNECT • DELETE • GET • HEAD • OPTIONS • PATCH • POST • PUT • TRACE
17. RESTful Routing GET /organizations - List Organizations GET /organizations/{id} - Show specific Organization POST /organizations - Create Organization POST /organizations/{id} - Update Organization (partial) PUT /organizations/{id} - Update Organization (full/overwrite) DELETE /organizations/{id} - Delete specific Organization
18. <?php Route::group(['prefix' => 'organizations' ], function() { Route::get('/', 'OrganizationsController@showList' ); Route::get('/{id}', 'OrganizationsController@show' ); Route::post('/', 'OrganizationsController@create' ); Route::post('/{id}', 'OrganizationsController@update' ); Route::put('/{id}', 'OrganizationsController@overwrite' ); Route::delete('/{id}', 'OrganizationsController@delete' ); });
19. Input: Types, Methods, & Formats 2 main methods of sending information: • Query parameters • Request body
20. Input: Types, Methods, & Formats Query parameters are good for READ requests (GET) • /people?per_page=30 When sending data (POST, PUT), a standard structure is best. • JSON in the request body
21. Input: Types, Methods, & Formats Why not just $_GET and $_POST? PHP is weird. • $_GET & $_POST have nothing to do with the HTTP method. • $_GET reads the query string from the URL • $_POST reads a query string from the request body IF the header “application/x-www-form-urlencoded” is present • $_POST - everything is a string
22. Input: Types, Methods, & Formats string(67) "organization%5Bname%5D=UpstatePHP&organization%5Bis_meeting% 5D=true" array(1) { ["organization" ]=> array(2) { ["name"]=> string(10) "UpstatePHP" ["is_meeting"]=> string(4) "true" } }
23. Input: Types, Methods, & Formats Sent as JSON: { "organization" : { "name": "UpstatePHP", "is_meeting": true } }
24. Input: Types, Methods, & Formats array(1) { ["organization" ]=> array(2) { ["name"]=> string(10) "UpstatePHP" ["is_meeting"]=> bool(true) } }
25. Response Formats What’s the norm? • JSON (pretty standard) • XML • HAL
26. Response Formats What should I choose? How do I choose? • Pick one and go with it… or • Let the user choose ◦ Header - Accept: application/json ◦ Extension - /organizations.json
27. Not all responses have a body. How can we tell what happened? But...
28. Response Codes FTW!
29. Response Codes 100s - Informational 200s - Success 300s - Redirect 400s - Client Error 500s - Server Error
30. Response Codes 200 - OK 201 - Created 202 - Accepted 204 - No Content 400 - Bad Request 401 - Unauthorized 403 - Forbidden 404 - Not Found 500 - Internal Server Error
31. Custom Error Codes Sometimes stock HTTP codes aren’t enough.
32. Custom Error Codes HTTP 400 • Validation errors • No activation code • Expired activation code • User already exists
33. Custom Error Codes Provide sanity where chaos reigns Custom codes allow a program to know specifically what type of error occurred Twitter does this well - https://dev.twitter.com/docs/error- codes-responses
34. Yay! We’re done right?
36. { "id":81, "name":"UpstatePHP", "description":"Hey! That's us!" , "url":"http://upstatephp.com" , "meta":null, "created_at":"2014-06-18 03:05: 43", "updated_at":"2014-06-18 03:05: 43" } { "id":81, "name":"UpstatePHP", "description":"Hey! That's us!" , "website":"http://upstatephp.com" , "meta":null, "created_at":"2014-06-18 03:05: 43", "updated_at":"2014-06-18 03:05:43" } • Schema changes (“url” -> “website”) can break a Client using our API • Exposes our table structure (BAD!!)
37. How do we avoid that?
38. Transformers!
39. $transformed = array( 'id' => (int) $organization ->id, 'name' => $organization ->name, 'description' => $organization - >description, 'url' => $organization ->website ); return Response::json($transformed); Benefits: • No more breaking changes • Type casting
40. That’s cool, but… is that it?
42. What if we could combine: • Transformers • Resources • Meta Data • Pagination and • Nested Resources
43. We can!
44. Fractal Demo time!