Designing great APIs

Learning fromJonathan Ive,Orwell, and the Kano Model

by Jon Dahl misc at Brightcove

API

API

API is an interface

Two users

What does this user want?

What does this user want?

API Design

George OrwellDieter RamsKano Model

George Orwell WritingDieter Rams Industrial DesignKano Model Product

Five guiding principles

Specific examples

Discuss

GeorgeOrwell

POST /things

USA Patriot Act

Expanded Surveillance Act

Propaganda

While freely conceding that the Soviet regime exhibits certain features which the humanitarian may be inclined to deplore, we must, I think, agree that a certain curtailment of the right to political opposition is an unavoidable concomitant of transitional periods, and that the rigors which the Russian people have been called upon to undergo have been amply justified in the sphere of concrete achievement.

I am not, indeed, sure whether it is not true to say that the Milton who once seemed not unlike a seventeenth-century Shelley had not become, out of an experience ever more bitter in each year, more alien to the founder of that Jesuit sect which nothing could induce him to tolerate.

Harold Laski, Essay in Freedom of Expression

I am not, indeed, sure whether it is not true to say that the Milton who once seemed not unlike a seventeenth-century Shelley had not become, out of an experience ever more bitter in each year, more alien to the founder of that Jesuit sect which nothing could induce him to tolerate.

I am not, indeed, sure whether it is not true to say that the Milton who once seemed not unlike a seventeenth-century Shelley had not become, out of an experience ever more bitter in each year, more alien to the founder of that Jesuit sect which nothing could induce him to tolerate.

1. Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.

2. Never use a long word where a short one will do.

3. If it is possible to cut a word out, always cut it out.

4. Never use the passive where you can use the active.

5. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.

6. Break any of these rules sooner than say anything outright barbarous.

Five guiding principles1. minimalism

Five guiding principles1. minimalism2. get out of the way

REST

Consistency

401 Unauthorized403 Forbidden

Dieter Rams

Jonathan Ive

Objectified (2009)

Five guiding principles1. minimalism2. get out of the way3. design for extremes

Dim strPname As StringDim dblPrice As Double

POST /api/jobs HTTP/1.1Accept: application/jsonContent-Type: application/json

{ "api_key" : "does not exist", "color" : "green"}

HTTP/1.1 500 Internal Server Error

HTTP/1.1 401 Unauthorized

HTTP/1.1 401 Unauthorized

{ "errors": [ "api_key not found" ]}

HTTP/1.1 401 Unauthorized

{ "errors": [ "api_key not found.", "api_key may not include spaces." ]}

HTTP/1.1 401 Unauthorized

{ "errors": [ "api_key not found. Please log in to https://example.com/account/api to retrieve your API key.", "api_key may not include spaces." ]}

POST /api/user HTTP/1.1Accept: application/jsonContent-Type: application/json

{ "api_key" : "A23B92F281CC" "strength" : 18}

HTTP/1.1 400 Bad Request

HTTP/1.1 400 Bad Request

{ "errors": [ "JSON is not valid. Syntax error, unexpected TSTRING, expecting '}' at line 2" ]}

HTTP/1.1 200 OK

HTTP/1.1 503 Service Unavailable

HTTP/1.1 408 Request Timeout

https://api.example.com/v1

913ebf20417e434390d56ccd81e54d1c

Five guiding principles1. minimalism2. get out of the way3. design for extremes4. be predictable

How do you charge money with Stripe?

What is the URL?What are the params?

curl https://api.stripe.com/v1/charges \ -u my_api_key: \ -d amount=20 \ -d currency=usd \ -d customer=12093155

KanoModel

NoriakiKano

NoriakiKano

Basic needs (must have)

Performance needs(one-dimensional)

Indifferent(don’t care)

Delighters(attractive, exciting)

Support

Focus on delight andperformance

Five guiding principles1. minimalism2. get out of the way3. design for extremes4. be predictable

Five guiding principles1. minimalism2. get out of the way3. design for extremes4. be predictable5. excite users

What do you think?

Thanks!

by Jon Dahl misc at Brightcove