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

Do Users Love Your API? Developer-Focused API D...

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.

Pete Holiday

April 21, 2015
Tweet

More Decks by Pete Holiday

Other Decks in Programming

Transcript

  1. What’s an API? An API is the way two pieces

    of software communicate across a boundary.
  2. 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"]
  3. Client.find_by first_name: 'Lifo' # => #<Client id: 1, first_name: "Lifo">

    Client.find_by first_name: 'Jon' # => nil Software Boundaries CLASS METHODS
  4. 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
  5. Bad API Experience? Easy stuff is hard Simple stuff is

    too complicated Too many end-points Docs are wrong or incomplete No wrapper libraries
  6. List Management Email Campaigns Reporting and Stats Keeping subscriber details

    up to date Creating and sending HTML emails Who is interacting with your emails
  7. Usage Patterns What are people using API v2.0 to do?

    LIST MANAGEMENT REPORTING OTHER CAMPAIGNS
  8. 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
  9. 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
  10. Tell Us What’s Wrong SO MANY METHODS API Key as

    a parameter of every call? Inconsistent naming How do you update merge fields?
  11. Use HTTP Basic Auth or OAuth Accept and serve JSON

    Make your API as RESTful as possible Follow, Don’t Lead
  12. 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 }
  13. 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
  14. 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
  15. REST’s
 6 Constraints 1. Client-Server Model 2. Stateless Server 3.

    Cacheable 4. Uniform Interface 5. Layered System 6. Code-on-Demand (Optional)
  16. REST’s
 6 Constraints 1. Client-Server Model 2. Stateless Server 3.

    Cacheable 4. Uniform Interface 5. Layered System 6. Code-on-Demand (Optional)
  17. 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
  18. List Management API RESTful API Resources: - Lists - Interest

    Groups - Merge Fields - Members - Segments - Reports
  19. Evaluating an existing API 1. Direct feedback from users 2.

    Hints from usage patterns 3. Rules of thumb for finding bad design
  20. ?