Your API Sucks

A presentation to be given by Ben Edmunds at CICONF 2012 on RESTful API Design and Implementation with CodeIgniter.

Transcript

1. Ben Edmunds @benedmunds http://benedmunds.com Your API Sucks CodeIgniter or RESTful API Design & Implementation
2. Who Am I Ben Edmunds @benedmunds http://benedmunds.com Build and lead development teams >10 years of experience in the industry Specialize in PHP development
3. Who Am I Ben Edmunds @benedmunds http://benedmunds.com Ion Auth http://github.com/benedmunds/CodeIgniter-Ion-Auth General http://github.com/benedmunds Open Source Contributions http://appstucco.com
4. Who Am I Personal: From Phenix City, AL Married for 6 years Work for Kforce Government Solutions Co-Founder of AppStucco Tech Focus: PHP (CodeIgniter, Laravel) Javascript (Node.js, Express, Phonegap) Databases (MySQL, PostGreSQL, MongoDB) Ben Edmunds @benedmunds http://benedmunds.com
5. What will we cover? RESTful API Basics API Design Implementing your API with CodeIgniter
6. RESTful API Basics
7. What is REST? Representational State Transfer HTTP Methods GET, POST, PUT, DELETE Expressive Real-World Usage
8. What is REST? Formats JSON* XML Anything
9. What is REST? Most widely used data format is JSON Javascript Object Notation { key: ‘value’, anotherKey: ‘value2’ }
10. What is REST? JSON usage in Javascript = familiar var object = { key: ‘value’, anotherKey: ‘value2’ };
11. What is REST? Outputs {key: ‘value’} PHP echo json_encode(array( ‘key’ => ‘value’ )); JSON encoding is supported in most languages
12. What is REST? Outputs array( ‘key’ => ‘value’ ) $json_data = “{key: ‘value’}”; print_r(json_decode($json_data)); JSON decoding is just as simple PHP
13. API Design Warning This will be Opinionated
14. API Design Simple Expressive Intuitive
15. API Design Simple Expressive Intuitive STABLE
16. API Design Simple Expressive Intuitive STABLE FUCKING STABLE
17. API Design Use the Facebook API DO THE OPPOSITE
18. API Design Document Your Shit!
19. API Design To ADD or not to ADD API Driven Development
20. API Design POST/PUT GET PUT DELETE HTTP Methods Create Read Update Delete =
21. API Design Different Opinions PUT = create (idempotent) POST = create (unknown resource) PUT = update (resource is known) Put vs Post
22. API Design URL endpoints represent their data Objects map to plural URLs A single Object maps to a singular URL Common actions across most objects
23. Let’s Put This All Together
24. API Design http://site.com/api/statuses Maps to all of the statuses “Statuses” could be: SQL table NoSQL collection Aggregate Data
25. API Design http://site.com/api/status/1234 Maps to a single status with the ID of 1234
26. API Design Creating If you know all of the data (including the ID) PUT http://site.com/api/status/1234
27. API Design Creating If you know all of the data (including the ID) PUT http://site.com/api/status/1234 No matter how many times you send this data only one resource should ever be created Idempotent
28. API Design Creating If you know all of the data (including the ID) PUT http://site.com/api/status/1234 { id: 1234, retweeted: false, active: true }
29. API Design Creating If you don’t know all of the data POST http://site.com/api/status
30. API Design Creating If you don’t know all of the data POST http://site.com/api/status Each time you post this data a new resource should be created Unique
31. API Design Creating If you don’t know all of the data POST http://site.com/api/status { retweeted: false, active: true }
32. API Design Reading Get all statuses GET http://site.com/api/statuses
33. API Design Reading Complex requests that require additional data GET http://site.com/api/statuses
34. API Design Reading Get all of the statuses that have been retweeted and are active - GET http://site.com/api/statuses /retweeted/true/active/true
35. API Design Update We know all of the identifying information so we PUT updates {active: true} PUT http://site.com/api/status/1234
36. API Design Delete Just pass the identifying information {id: 1234} DELETE http://site.com/api/status
37. API Design Relationships Get the user that posted a status GET http://site.com/api/status/1234/user
38. What About Versioning? Looks like @iamfiscus
39. API Design How to handle versioning? GET http://site.com/api/v1/statuses GET http://site.com/api/v2/statuses Each version has a separate route -
40. API Design How to handle versioning? Route newest API through http://api.site.com OR http://site.com/api GET http://site.com/api/v2/statuses GET http://site.com/api/statuses =
41. Finally Let’s Make Something
42. Implementation Phil Sturgeon’s CodeIgniter REST Server http://github.com/philsturgeon/codeigniter- restserver What We Will Use
43. Implementation application - config - controllers - models - views - ... system - index.php Directory structure
44. Implementation Example Index Page
45. Implementation Users #1 - JSON
46. Implementation application - config - rest.php controllers - models - views - ... system - index.php Setup the config
47. Implementation ... $config['rest_default_format'] = 'json'; ... Setup the config
48. Implementation API Design for a Status
49. Implementation Creating POST /status {user_id: 1, text: ‘Test Status’ } Ouput {succes: true, id: 1 }
50. Implementation Reading GET /status/id/1 {id: 1, user_id: 1, text: ‘Test Status’ } Ouput {success:true}
51. Implementation Updating PUT /status {id: 1, user_id: 1, text: ‘Test Status - Updated’ } Ouput {success:true}
52. Implementation Deleting DELETE /status {id: 1} Ouput {success:true}
53. Implementation application - config - controllers - api - v1.php models - views - ... system - index.php Create the controller
54. Implementation GET /status/id/1 = function status_get function status_get() { if (!$this->get('id')) { $this->response(array('error' => 'ID is required'), 404); } $status = $this->status_m->get( $this->get('id') ); if ($status) { $this->response($status, 200); } else { $this->response(array('error' => 'Status not be found'), 404); } }
55. Implementation GET /status/id/1 if (!$this->get('id')) { $this->response( array( ‘success’ => FALSE, 'error' => 'ID is required' ), 404); } Require the ID param. Send an error response.
56. Implementation GET /status/id/1 $status = $this->status_m->get( $this->get('id') ); if ($status) { $response = array( ‘success’ => TRUE, ‘status‘ => $status ); $this->response($response, 200); } else { $this->response(array( ‘success’ => FALSE, 'error' => 'Status not be found' ), 404); } Get the status. Pass the status in the response. Else send an error response.
57. Implementation GET /status/id/1
58. Implementation function status_post() { $data = array( ‘user_id’ => $this->post(‘user_id’), ‘text‘ => $this->post(‘text’), ); $status_id = $this->status_m->insert($data); if ($status) { $this->response(array( 'success' => TRUE, 'id' => $status_id ), 200); } //error goes here } POST /status = function status_post
59. Implementation function status_post() { $id = $this->put(‘id’); $data = array( ‘user_id’ => $this->put(‘user_id’), ‘text‘ => $this->put(‘text’), ); $updated = $this->status_m->update($id, $data); if ($updated) { $this->response(array( 'success' => TRUE ), 200); } //error goes here } PUT /status = function status_put
60. Implementation function status_delete() { $id = $this->delete(‘id’); $deleted = $this->status_m->delete($id); if ($deleted) { $this->response(array( 'success' => TRUE ), 200); } //error goes here } DELETE /status = function status_delete
61. Finale Go make cool shit
62. Community http://github.com/EllisLab/CodeIgniter http://github.com/philsturgeon/ codeigniter-restserver http://codeigniter.com/
63. Ben Edmunds @benedmunds http://benedmunds.com THANKS! Your API Sucks CodeIgniter