Building APIs Developers Love (LCA2014)

A talk from LinuxConf Australia 2014 in Perth, Australia on what helps make a good API design and common gotchas that different APIs need to deal with.

Transcript

1. Hello!
2. I'm Darcy Any questions? sutto@sutto.net / @sutto
3. Building APIs that Developers ❤️!
4. We're talking about HTTP
5. Why are Open APIs Important?
6. Increasingly becoming defining interface to services
7. E.g. Amazon S3 API for Storage, Twitter for Communication
8. Free support for a huge variety of existing tools
9. HTTP as the transport layer
10. Language agnostic helps with abstraction
11. HTTP has legacy
12. Rich Internet Applications & Mobile Applications
13. The web as a system of interconnected pieces
14. Why build an API vs Open Sourcing the Code?
15. Open Sourcing isn't always feasible
16. Logistics
17. Licensing / IP
18. Operational
19. Simpler Facade / Interface
20. Lower Barrier to Entry for Consumption
21. Building Good Apis
22. Simple, Consistent Structure
23. Keep Serialization Simple
24. XML or JSON
25. … but mainly JSON
26. Simpler objects building the bigger picture
27. Serialized versions based on context
28. e.g. full object vs compact object
29. Collection+JSON, HAL and the like
30. Addendum: http://jsonapi.org/ is an excellent reference point
31. Well-considered Errors
32. Errors aren't just for the libraries, must be for the developer
33. Unique error identifier + human readable description
35. String identifiers convey more than numeric codes
36. … but still use HTTP error codes
37. … and serve the correct content type
38. Document errors across the whole API and specific sections
39. Make it easy to explore & experiment
40. People will explore your API
41. Encourage that
42. curl & wget
43. … and don't forget the humble browser.
44. Side note: httpie is *wonderful*
46. Change is inevitable
47. Easier to design for it than to bolt it on
48. What are you versioning?
49. - versus - Versioning Data Versioning Semantics
50. - versus - Header based Path based
51. Content-Type negotiation
52. Designing for change
53. Understand the best choice for you
54. Embrace HTTP
55. HTTP can be simple
56. … but it can also be hard
57. Source: https://github.com/basho/webmachine/wiki/Diagram
58. Lots of small pieces that are key
59. Status Codes Methods Content Negotiation
60. Headers for Metadata
61. Caching
62. Don't reinvent what's already there.
63. SPDY & HTTP 2.0
64. Don't reinvent Auth
65. Powerful, Easy to use, Secure
66. Hard to balance all three
67. … so don't reinvent the wheel
68. HTTP Authorization Header
69. OAuth / OAuth2
70. Avoid developers having to write custom code to handle your auth
71. API Design Approaches
72. RPC
73. JSON-RPC / XML-RPC
74. SOAP & others
75. Resource-based APIs
76. HATEOAS vs. “REST”
77. Graph-based APIs
78. Hypermedia
79. Documentation is critical
80. Good documentation is even more important than a good design
81. Thoroughly document data choices
82. … and document how the api itself works
83. Automatic Tooling is improving
84. but hand written stills wins
85. Make examples language-agnostic
86. Choose your tooling wisely
87. Tools to simplify, not to completely abstract.
88. Build for the web, not your language of choice.
89. You should still care / be dealing with some parts of HTTP
90. Actually use it.
91. Good APIs aren't just designed for computers.
92. Great APIs are designed for humans.
93. Embracing Open APIs
94. Don't build yet another, completely custom take on things
95. … as the tendency as programmers is to do
96. Emphasis simplicity
97. Using Standardised & Documented Structures
98. Expose as much data as is feasible early on
99. Use standardised solutions for given issues (e.g. Auth)
100. Think of it as an interface, not a mirror of the implementation
101. Encourage diverse implementations
102. But most importantly, solve a real problem — not a perceived one.
103. Questions?
104. Facebook Graph API:
 https://developers.facebook.com/docs/graph-api/ Apiary (API Tools): http://apiary.io/ JSON API Spec
 http://jsonapi.org/ httpie:
 http://httpie.org/ Previous API talk (Ruby-oriented):
 http://blog.ninjahideout.com/posts/api-driven-applications- with-rails