Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Do Users Love Your API? Developer-Focused API Design

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.

50f5c5337553cbb60499d174bb50a765?s=128

Pete Holiday

April 21, 2015
Tweet

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
  11. None
  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

  46. None