Slide 1

Slide 1 text

Do Users Love Your API? Developer-Focused API Design

Slide 2

Slide 2 text

Hello, World! Pete Holiday
 Lead Engineer
 @toomuchpete Kate Harlan
 Engineering Intern


Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

What Developers Want

Slide 9

Slide 9 text

APIs Are Forever

Slide 10

Slide 10 text

Bad API Experience? Easy stuff is hard Simple stuff is too complicated Too many end-points Docs are wrong or incomplete No wrapper libraries

Slide 11

Slide 11 text

No content

Slide 12

Slide 12 text

Our mission is to help people send better emails.

Slide 13

Slide 13 text

Main Features LISTS CAMPAIGNS REPORTING

Slide 14

Slide 14 text

List Management Email Campaigns Reporting and Stats Keeping subscriber details up to date Creating and sending HTML emails Who is interacting with your emails

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

Tell Us What’s Wrong SO MANY METHODS API Key as a parameter of every call? Inconsistent naming How do you update merge fields?

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

Follow, Don’t Lead

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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 }

Slide 27

Slide 27 text

The Most Important Slide ® DON’T BE CLEVER

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

If the Web Worked Like APIs Do

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

Resource Representations

Slide 35

Slide 35 text

Self-Describing Messages

Slide 36

Slide 36 text

HATEOAS

Slide 37

Slide 37 text

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

Slide 38

Slide 38 text

THIS IS NOT WHAT I SIGNED UP FOR

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

What We Did MailChimp API v3.0 Notes

Slide 44

Slide 44 text

?

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

No content