Sunshine PHP 2015 - Your API is Bad and You Should Feel Bad

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

2. Title Title Ben Edmunds Open Source Author PHP Town Hall Podcast CTO at Mindfulware Who is this guy?
3. Title Title Ben Edmunds @benedmunds http://benedmunds.com Who is this guy?
4. Title Title RESTful API Basics API Design Implementing your API Versioning, Auth, & Rate Limiting What Will We Cover?
5. Title Title RESTful API Basics
6. Title Title Representational State Transfer HTTP Methods GET, POST, PUT, DELETE Expressive Real-World Usage What is REST?
7. Title Title Formats JSON* XML Anything What is REST?
8. Title Title Most widely used data format is JSON Javascript Object Notation { key: ‘value’, anotherKey: ‘value2’ } What is REST?
9. Title Title JSON usage in Javascript = familiar var object = { key: ‘value’, anotherKey: ‘value2’ }; What is REST?
10. Title Title Outputs {key: ‘value’} PHP echo json_encode(array( ‘key’ => ‘value’ )); JSON encoding is supported natively in most languages What is REST?
11. Title Title Outputs array( ‘key’ => ‘value’ ) $json_data = “{key: ‘value’}”; print_r(json_decode($json_data)); JSON decoding is just as simple PHP What is REST?
12. Warning This will be Opinionated
13. Title Title Simple Expressive Intuitive API Design
14. Title Title Simple Expressive Intuitive STABLE API Design
15. Title Title Simple Expressive Intuitive STABLE CONSISTENT API Design
16. Title Title Use the Facebook API DO THE OPPOSITE API Design
17. Title Title Document! Document! Document! API Design
18. Title Title To ADD or not to ADD API Driven Development API Design
19. Title Title HTTP Status Codes HTTP Status Cats to the Rescue! API Design
20. Title Title Status 2xx = Success API Design
21. Title Title Status 3xx = Redirect API Design
22. Title Title Status 4xx = Client Errors API Design
23. Title Title Status 5xx = Service Errors API Design
24. Title Title VERBS API Design
25. Title Title POST/PUT GET PUT DELETE HTTP Methods Create Read Update Delete = API Design
26. Title Title POST/PUT = Create api.domain.com/user PUT if all values are known API Design
27. Title Title GET = READ api.domain.com/user/2 API Design
28. Title Title PUT = IDEMPOTENT Needs all identifying info Basically, include the ID API Design
29. Title Title Different Opinions PUT = create (idempotent) POST = create (unknown resource) PUT = update (resource is known) Put vs Post API Design
30. Title Title PUT = UPDATE api.domain.com/user/2 { id: 2, first_name: ‘bob’, last_name: ‘cat’ } API Design
31. Title Title DELETE = DELETE api.domain.com/user/2 API Design
32. Title Title CONSISTENCY API Design
33. Title Title URL endpoints represent data /user = user /company = company API Design
34. Title Title A single Object maps to a singular URL api.domain.com/user/2 api.domain.com/company/3 API Design
35. Title Title Objects map to plural URLs api.domain.com/users api.domain.com/companies API Design
36. Title Title Common actions across most objects GET /user/2 GET /company/3 DELETE /user/2 DELETE /company/3 API Design
38. Title Title https://site.com/api/statuses Maps to all of the statuses “Statuses” could be: SQL table NoSQL collection Aggregate Data API Design
39. Title Title https://site.com/api/status/1234 Maps to a single status with the ID of 1234 API Design
40. Title Title Creating If you know all of the data (including the ID) PUT https://site.com/api/status/1234 API Design
41. Title Title 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 API Design
42. Title Title Creating If you know all of the data (including the ID) PUT https://site.com/api/status/1234 { id: 1234, retweeted: false, active: true } API Design
43. Title Title Creating If you don’t know all of the data POST https://site.com/api/status Implementation
44. Title Title 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 Implementation
45. Title Title Creating If you don’t know all of the data POST https://site.com/api/status {user_id: 1, text: ‘Test Status’ } Implementation
46. Title Title 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 } Implementation
47. Title Title Reading Get all statuses GET https://site.com/api/statuses API Design
48. Title Title Reading Complex requests that require additional data GET https://site.com/api/statuses API Design
49. Title Title Reading Get all of the statuses that have been retweeted and are active GET https://site.com/api/statuses ? retweeted=1&active=1 API Design
50. Title Title Updating We know all of the identifying information so we PUT updates API Design
51. Title Title Updating We know all the data PUT https://site.com/api/status/123 {id: 123, user_id: 1, text: ‘Test Status 2’ } Implementation
52. Title Title Delete Just pass the identifying information {id: 123} DELETE https://site.com/api/status/123 API Design
53. Title Title Relationships Get the user that posted a status GET https://site.com/api/status/1234/user API Design
55. Title Title How to handle versioning? GET https://site.com/api/v1/statuses GET https://site.com/api/v2/statuses Each version has a separate route - Versioning
56. Title Title 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 = Versioning
57. Title Title How to handle versioning? Accept Headers (HATEOAS) Versioning Accept: application vnd.github.user.v4+json
58. -OAS
59. Title Title Content Negotiation HATEOAS Hypermedia Controls
60. Title Title Content Negotiation Accept: application:x-yaml Accept: application:json Request “Accept” Header (JSON,XML,YAML, etc) Versioning
61. Title Title Content Negotiation Allow: GET, PUT, POST OPTIONS Http Request Versioning
62. Title Title Hypermedia Controls Links to Related Content Versioning { success: true, id: 123, links: { “rel”: ‘self’ “url”: ‘/status/123’ }, { “rel”: ‘user’ “url”: ‘/status/123/user’ } }
63. Title Title Hypermedia Controls Links to Related Content Versioning { success: false, error: { “code”:‘errorFail’ “message”: ‘You have Failed!’ “url”: ‘http://domain.com/docs/errorFail’ } }
65. Title Title Who’s the Consumer? User Service Internal Service Authentication
66. Title Title Consumer = User OAuth Client Server Request Token -> <- Access Token Authentication
67. Title Title Consumer = User Standard Many Diff “Flows” Complicated Spec OAuth 2 Authentication
68. Title Title Consumer = User Client Server Request -> w/AccessToken OAuth 2 Authentication
69. Title Title Consumer = Internal Client Server Request -> w/AccessToken Access Token = Service Key+Client Key Authentication
70. Title Title Data Hash SHA1 ( $DATA ) Authentication
72. Title Title Prevent Abuse Maintain Availability Client Key IP Address User ID Rate Limiting
74. Title Title How to debug as you develop? CURL Automated Tests Rested on OSX Debugging
75. Go Make Cool Things
76. Title Title https://leanpub.com/build-apis-you-wont-hate Book - Build APIs You Won’t Hate Tutorial - Demystifying REST https://tutsplus.com/tutorial/demystifying-rest/ Resources
77. Title Title http://aaronparecki.com/articles/ 2012/07/29/1/oauth2-simplified Blog - OAuth 2 Simplified Book - OAuthello https://leanpub.com/oauthello-a-book-about- oauth/ Resources
78. Title Title BuildSecurePHPapps.com Coupon Code: sunshine2015 $3 off http://buildsecurephpapps.com/?coupon=sunshine2015 Resources
79. Q/A TIME! https://joind.in/13438 Ben Edmunds @benedmunds http://benedmunds.com http://buildsecurephpapps.com/?coupon=sunshine2015