Building Better Web APIs (PyCon AU 2014)

Web APIs are how much of the modern web speaks - services speaking HTTP and JSON are ubiquitous, and nearly everything from your phone to your TV interacts with one of them. We'll go over how APIs are structured and versioned, why you should validate your data, and why you should have them in the first place -- and what other best practices are when creating them.

Transcript

1. hawkowl@atleastfornow.net @hawkieowl
3. technicals.atleastfornow.net
4. Building Better Web APIs
5. Why do we need Web APIs?
6. APIs are how applications talk
7. Implement once, access anywhere
8. Break open the silo!
9. And it’s two way!
10. And can be automated!
11. The applications are massive
12. Web 3.0 The Internet Of Things
13. Web 3.0 The Internet Of Things
14. The Programmable Internet
16. Rich APIs == Automation Wins
17. The Benefits
18. Implementing Web APIs
19. Who are our users?
20. Design for the End User • Expose all the data that the user might need • Provide encrypted endpoints
21. Design for the Implementor • Design to the principal of least surprise and lay your resources out in a consistent way • Provide a platform which will cause little need for modification down the line • Provide documentation which adequately and completely explains your API and its semantics - provide examples!!!!
22. Versioning
23. Explicit versions are essential for stability
24. Provide API Pinning
25. Pinning Methods • URI • route53.amazonaws.com/2013-04-01/hostedzone • Header • ‘Stripe-Version: 2014-06-17’ • ‘Accept: application/vnd.heroku +json; version=3’
26. Your version should be in your API’s URI
27. For example: v1.api.example.com (better)
 api.example.com/v1/ (best)
28. –Tim Berners-Lee (http://www.w3.org/Provider/Style/URI.html) “Cool URIs don't change.”
29. /v1/resource == /v2/resource ?
30. Different versions have different responses and resource layout
31. Layout
32. Resources, not functions
33. /cakes/1 is better than /get_cake?id=1
34. /cakes is better than /get_all_cakes
35. POST to /cakes is better than POST to /make_cake
36. /cakes/1/layers/1 is better than /get_cake_layer?cake_id=1&layer_id=1
37. /cakes/1/layers/1/icing is better than /get_cake_layer_icing?cake_id=1&layer_id=1
38. REST
39. REST is best
40. REST maps state transforms to HTTP methods
41. REST in 2014 • GET fetches (RFC 7231) • POST is resource specific (RFC 7231) • PUT replaces or creates (RFC 7231) • PATCH updates (RFC 5789) • DELETE removes (RFC 7231)
42. Do what makes sense, be pragmatic!
43. But just in case, document it anyway
44. Documentation
45. Document side-effects
46. Don’t be afraid to copy good documentation styles
47. Stripe: Good!
48. Mailgun: Good!
49. Mailgun: Good!
50. Linode… not so good
51. Validation
52. Validation is great
53. On output, as well!
54. Django REST Framework: Use typed fields
55. JSON Schema is framework-agnostic
56. Speed
57. 100 Continue can save time & bandwidth
58. …but you can’t use it with WSGI
59. Stateless workers for better scaling
60. My Research
61. Haddock https://github.com/hawkowl/haddock
62. Saratoga https://github.com/hawkowl/saratoga
63. Tool Improvements
64. Better tools mean better result for the same effort
65. Versioning
66. Validation
67. Documentation
68. Other things I couldn’t fit inside 20 minutes…
69. Testing
70. RPC over REST
71. Authentication Methods
72. …but do fit on a website
73. HawkOwl’s Technicals technicals.atleastfornow.net
74. Questions! Twitter: @hawkieowl