SkiPHP 2014 - Your API Sucks

Do you hate the Facebook API? We all do as well. So stop writing your API in their footsteps.

In this talk we will walk through how to construct a RESTful API, what makes an API your users/developers will love, and why you should eat your own dog food with API Driven Development.

Transcript

1. Your API Sucks
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
4. Who Am I Personal: From Alabama (hence the accent) Living in Portland, OR ! Tech Focus: PHP (CodeIgniter, Laravel, Slim) Javascript (Backbone, Angular, Node.js, Express, Phonegap) Databases (MySQL, PostGreSQL) Ben Edmunds @benedmunds http://benedmunds.com
5. What will we cover? RESTful API Basics ! API Design ! Implementing your API ! Versioning, Auth, & Rate Limiting !
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 natively 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 CONSISTENT
17. API Design Use the Facebook API ! DO THE OPPOSITE
18. API Design Document! Document! Document!
19. API Design To ADD or not to ADD API Driven Development
20. API Design HTTP Status Codes HTTP Status Cats to the Rescue! !
21. API Design Status 2xx = Success
22. API Design Status 3xx = Redirect
23. API Design Status 4xx = Client Errors
24. API Design Status 5xx = Service Errors
25. API Design VERBS
26. API Design POST/PUT GET PUT DELETE HTTP Methods Create Read Update Delete =
27. API Design POST/PUT = Create api.domain.com/user PUT if all values are known
28. API Design GET = READ api.domain.com/user/2
29. API Design PUT = IDEMPOTENT Needs all identifying info ! Basically, include the ID
30. API Design Different Opinions ! PUT = create (idempotent) POST = create (unknown resource) ! PUT = update (resource is known) Put vs Post
31. API Design PUT = UPDATE api.domain.com/user/2 { id: 2, first_name: ‘bob’, last_name: ‘cat’ }
32. API Design DELETE = DELETE api.domain.com/user/2
33. API Design CONSISTENCY
34. API Design URL endpoints represent data /user = user /company = company
35. API Design A single Object maps to a singular URL api.domain.com/user/2 api.domain.com/company/3
36. API Design Objects map to plural URLs api.domain.com/users api.domain.com/companies
37. API Design Common actions across most objects GET /user/2 GET /company/3 ! DELETE /user/2 DELETE /company/3
38. Let’s Put This All Together
39. API Design https://site.com/api/statuses ! Maps to all of the statuses ! “Statuses” could be: SQL table NoSQL collection Aggregate Data
40. API Design https://site.com/api/status/1234 ! Maps to a single status with the ID of 1234
41. API Design Creating ! If you know all of the data (including the ID) ! PUT https://site.com/api/status/1234
42. API Design Creating ! If you know all of the data (including the ID) ! PUT https://site.com/api/status/1234 No matter how many times you send this data only one resource should ever be created Idempotent
43. API Design Creating ! If you know all of the data (including the ID) ! PUT https://site.com/api/status/1234 { id: 1234, retweeted: false, active: true }
44. Implementation Creating ! If you don’t know all of the data ! POST https://site.com/api/status
45. Implementation Creating Each time you post this data a new resource should be created Unique ! If you don’t know all of the data ! POST https://site.com/api/status
46. Implementation Creating ! If you don’t know all of the data ! POST https://site.com/api/status {user_id: 1, text: ‘Test Status’ }
47. Implementation Creating ! If you don’t know all of the data ! POST https://site.com/api/status {user_id: 1, text: ‘Test Status’ } Response {succes: true, id: 123 }
48. API Design Reading ! ! Get all statuses GET https://site.com/api/statuses
49. API Design Reading Complex requests that require additional data ! ! GET https://site.com/api/statuses
50. API Design Reading Get all of the statuses that have been retweeted and are active GET https://site.com/api/statuses ? retweeted=1&active=1
51. API Design Updating We know all of the identifying information so we PUT updates
52. Implementation Updating ! We know all the data ! PUT https://site.com/api/status/123 {id: 123, user_id: 1, text: ‘Test Status 2’ }
53. API Design Delete Just pass the identifying information {id: 123} DELETE https://site.com/api/status/123
54. API Design Relationships Get the user that posted a status GET https://site.com/api/status/1234/user
55. What About Versioning?
56. Versioning How to handle versioning? GET https://site.com/api/v1/statuses ! GET https://site.com/api/v2/statuses Each version has a separate route -
57. Versioning How to handle versioning? Route newest API through https://api.site.com GET https://site.com/api/v2/statuses GET https://site.com/api/statuses =
58. Authentication
59. Authentication Who’s the Consumer? User Service ! Internal Service
60. Authentication Consumer = User OAuth Client Server Request Token -> <- Access Token !
61. Authentication Consumer = User Standard Many Diff “Flows” Complicated Spec OAuth 2
62. Authentication Consumer = User ! Client Server Request -> w/AccessToken ! OAuth 2
63. Authentication Consumer = Internal Client Server Request -> w/AccessToken ! Access Token = Service Key+Client Key
64. Authentication Data Hash SHA1 ( $DATA )
65. Rate Limiting
66. Rate Limiting Prevent Abuse Maintain Availability Client Key IP Address User ID
67. Debugging
68. Debugging How to debug as you develop? CURL Automated Tests Rested on OSX
69. Finale Go Make Cool Things
70. Resources https://leanpub.com/build-apis-you-wont-hate Book - Build APIs You Won’t Hate Tutorial - Demystifying REST https://tutsplus.com/tutorial/demystifying-rest/
71. Resources http://aaronparecki.com/articles/ 2012/07/29/1/oauth2-simplified Blog - OAuth 2 Simplified Book - OAuthello https://leanpub.com/oauthello-a-book-about- oauth/
72. THANKS! https://joind.in/10413 Ben Edmunds @benedmunds http://benedmunds.com