Do Users Love Your API? Developer-Focused API Design

Presented at RailsConf 2015: A few months after launching v2.0 of MailChimp’s API, it was already falling short of our expectations. In every area, problems were slowing our users down and getting in their way. After finding our attempts to fix the problems uninspiring, we decided to start over.

In this workshop we’ll walk you through our processes (from evaluation of v2.0 through implementation of v3.0) and share the lessons we learned while trying to fix an API that serves more than a billion requests per month. Join us for this crash course on building an API optimized for developer happiness.

Transcript

1. Do Users Love Your API? Developer-Focused API Design
2. Hello, World! Pete Holiday
 Lead Engineer
 @toomuchpete Kate Harlan
 Engineering Intern

3. What’s an API? An API is the way two pieces of software communicate across a boundary.
4. Software Boundaries RUBY BLOCKS a = [ "a", "b", "c", "d" ] a.collect { |x| x + "!" } #=> ["a!", "b!", "c!", "d!"] a.map.with_index { |x, i| x * i } #=> ["", "b", "cc", "ddd"]
5. Client.find_by first_name: 'Lifo' # => #<Client id: 1, first_name: "Lifo"> Client.find_by first_name: 'Jon' # => nil Software Boundaries CLASS METHODS
6. GET /3.0/lists HTTP/1.1 content-type:application/json charset=utf-8 host: https://us1.api.mailchimp.com content-length:0 { "lists": [ { "id": "a5044a8a4f", "web_id": 583721, "name":"Rubyist Monthly" } ], "total_items": 1 } Software Boundaries WEB SERVICES
7. Developer-Focused? Choosing to prioritize great developer experience, even when that makes the design harder to implement.
8. What Developers Want
9. APIs Are Forever
10. Bad API Experience? Easy stuff is hard Simple stuff is too complicated Too many end-points Docs are wrong or incomplete No wrapper libraries
12. Our mission is to help people send better emails.
13. Main Features LISTS CAMPAIGNS REPORTING
14. List Management Email Campaigns Reporting and Stats Keeping subscriber details up to date Creating and sending HTML emails Who is interacting with your emails
15. Who Uses Our API? WEB SERVICES CUSTOMERS CUSTOMERS MAILCHIMP MOBILE APPS
16. Usage Patterns What are people using API v2.0 to do? LIST MANAGEMENT REPORTING OTHER CAMPAIGNS
17. Evaluating MailChimp’s API 1. Have a hypothetical customer in mind. 2. How might that customer might use the API? 3. Critique the API with your neighbors
18. List Management Editing Lists Merge Fields Interest Groups Managing Subscribers Segmentation Statistics and Reporting
19. What’s Our Intent? Getting customers on our lists Keeping their data up to date Organizing our list in certain ways Sending to certain groups Stats for our Boss
20. Tell Us What’s Wrong SO MANY METHODS API Key as a parameter of every call? Inconsistent naming How do you update merge fields?
21. Principles of Developer-Driven API Design Design for Intent Limit Your API’s Mental Footprint
22. Design For Intent Each end-point should have a purpose; common operations should only take one call
23. Follow, Don’t Lead
24. Use HTTP Basic Auth or OAuth Accept and serve JSON Make your API as RESTful as possible Follow, Don’t Lead
25. Use HTTP methods properly Use appropriate HTTP response codes Principle of Least Astonishment
26. Principle of Least Astonishment Please Don’t Ever Do This HTTP/1.1 200 OK Content-Type: application/json;charset=utf-8 Content-Length: length { "success": false }
27. The Most Important Slide ® DON’T BE CLEVER
28. Let’s Talk About REST • REST is an architectural style, not a standard • Coined by Roy Fielding in a Ph.D. Thesis in 2000 • The WWW is living proof of the power of REST
29. If the Web Worked Like APIs Do
30. Responses: • 2xx: Success • 3xx: Redirect • 4xx: User Error • 5xx: Server Error HTTP at a Glance Methods: • Create: POST/PUT • Read: GET • Update: PATCH/PUT • Delete: DELETE
31. REST’s
 6 Constraints 1. Client-Server Model 2. Stateless Server 3. Cacheable 4. Uniform Interface 5. Layered System 6. Code-on-Demand (Optional)
32. REST’s
 6 Constraints 1. Client-Server Model 2. Stateless Server 3. Cacheable 4. Uniform Interface 5. Layered System 6. Code-on-Demand (Optional)
33. Resource Identifiers Each resource should live at it’s own address
34. Resource Representations
35. Self-Describing Messages
36. HATEOAS
37. Richardson Maturity Model The Swamp of POX Resources HTTP Verbs Hypermedia Controls Glory of REST
38. THIS IS NOT WHAT I SIGNED UP FOR
39. Designing an API Let’s Fix MailChimp’s List Management API!
40. What’s Our Intent? Getting customers on our lists Keeping their data up to date Organizing our list in certain ways Sending to certain groups Stats for our Boss
41. List Management API RESTful API Resources: - Lists - Interest Groups - Merge Fields - Members - Segments - Reports
42. Evaluating an existing API 1. Direct feedback from users 2. Hints from usage patterns 3. Rules of thumb for finding bad design
43. What We Did MailChimp API v3.0 Notes
44. ?
45. 042> print 'Thank you!' Thank you! => nil 043> exit