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
   

   View Slide

2. Hello, World!
   Pete Holiday

   Lead Engineer

   @toomuchpete
   Kate Harlan

   Engineering Intern

   

   View Slide

3. What’s an API?
   An API is the way two pieces of software
   communicate across a boundary.
   

   View Slide

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"]
   

   View Slide

5. Client.find_by first_name: 'Lifo'
   # => #
   Client.find_by first_name: 'Jon'
   # => nil
   Software Boundaries CLASS METHODS
   

   View Slide

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
   

   View Slide

7. Developer-Focused?
   Choosing to prioritize great developer
   experience, even when that makes the design
   harder to implement.
   

   View Slide

8. What Developers Want
   

   View Slide

9. APIs Are Forever
   

   View Slide

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
    

    View Slide

11. View Slide

12. Our mission is to help
    people send better emails.
    

    View Slide

13. Main Features
    LISTS CAMPAIGNS REPORTING
    

    View Slide

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
    

    View Slide

15. Who Uses Our API?
    WEB
    SERVICES
    CUSTOMERS
    CUSTOMERS
    MAILCHIMP
    MOBILE APPS
    

    View Slide

16. Usage Patterns
    What are people
    using API v2.0 to do?
    LIST
    MANAGEMENT
    REPORTING
    OTHER
    CAMPAIGNS
    

    View Slide

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
    

    View Slide

18. List Management
    Editing Lists
    
    Merge Fields
    
    Interest Groups
    
    Managing Subscribers
    
    Segmentation
    
    Statistics and Reporting
    

    View Slide

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
    
    

    View Slide

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?
    

    View Slide

21. Principles of Developer-Driven API Design
    Design for Intent
    Limit Your API’s Mental Footprint
    

    View Slide

22. Design For Intent
    Each end-point should have a purpose; common
    operations should only take one call
    

    View Slide

23. Follow, Don’t Lead
    

    View Slide

24. Use HTTP Basic Auth or OAuth
    Accept and serve JSON
    Make your API as RESTful as possible
    Follow, Don’t Lead
    

    View Slide

25. Use HTTP methods properly
    Use appropriate HTTP response codes
    Principle of Least Astonishment
    

    View Slide

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
    }
    

    View Slide

27. The Most Important Slide ®
    DON’T BE
    
    CLEVER
    

    View Slide

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
    

    View Slide

29. If the Web Worked Like APIs Do
    

    View Slide

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
    

    View Slide

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)
    

    View Slide

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)
    

    View Slide

33. Resource Identifiers
    Each resource should live at it’s own address
    

    View Slide

34. Resource Representations
    

    View Slide

35. Self-Describing Messages
    

    View Slide

36. HATEOAS
    

    View Slide

37. Richardson Maturity Model
    The Swamp of POX
    Resources
    HTTP Verbs
    Hypermedia Controls
    Glory of REST
    

    View Slide

38. THIS IS NOT WHAT I SIGNED UP FOR
    

    View Slide

39. Designing an API
    Let’s Fix MailChimp’s List Management API!
    

    View Slide

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
    
    

    View Slide

41. List Management API
    RESTful API Resources:
    - Lists
    - Interest Groups
    - Merge Fields
    - Members
    - Segments
    - Reports
    

    View Slide

42. Evaluating an existing API
    1. Direct feedback from users
    
    2. Hints from usage patterns
    
    3. Rules of thumb for finding bad design
    

    View Slide

43. What We Did
    MailChimp API v3.0 Notes
    

    View Slide

44. ?
    

    View Slide

45. 042> print 'Thank you!'
    Thank you! => nil
    043> exit
    

    View Slide

46. View Slide