Advanced API Design: how an awesome API can help you make friends, get rich, and change the world

Advanced API DesignHow an awesome API can

attract friends, make you rich,

and change the world

Jon Dahl@jondahl

[email protected]

ApplicationProgrammingInterface

UserInterface

Interface

LibrarySDK

Net::SSH

Web Service

SimpleObjectAccessProtocol

SimpleObjectAccessProtocol

REST

HTTP

Web is an API

GET /records

POST /record/new

POST /record/new<xml> <data>Foo</data></xml>

POST /record/new{ "data" : "foo"}

(Don’t tell our investors that we don’t have a real product)

Some Examples

1. Second InterfaceFlickrTwitterLinkedinFacebookPaypalGoogle Maps

2. Internal APIsService Oriented ArchitectureMobile application backends

3. Core TechAmazon Web ServicesTwilioGeoloqiZencoderSendgrid FactualSpreedlyRecurlySaploTropoCloudMailinUploadJuicer

4. Science FictionPiCloudAmazon Mechanical Turk...

so, how do you design a good API?

Competitive Advantage

REST conventions

GET POSTPUTDELETE

recordsjobsmessagesserversusers

HTTP codes

200 OK201 Created202 Accepted

400 Bad Request401 Unauthorized402 Payment Required404 Not Found409 Conflict418 I’m a teapot422 Unprocessable Entity

500 Internal Server Error503 Service Unavailable

... and many more!

Version it

GET /api/records/38927

{ "color" : "green", "velocity" : 1000000}

GET /api/records/38927

{ "color" : "10EE33", "velocity" : 1000000}

GET /api/v1/records/38927

{ "color" : "green", "velocity" : 1000000}

GET /api/v2/records/38927

{ "color" : "10EE33", "velocity" : 1000000}

GET /api/records/38927?version=2

GET /api/v2/records/38927

GET /api/records/38927Accept: application/json+v2

Smart validations

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

{ "api_key" : "Not A Real Key", "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" ]}

JSON + XML

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

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

params[:strength] # 18

respond_to do |wants| wants.json { render :json => @jobs.to_json } wants.xml { render :xml => @jobs.to_xml } end

Document it

Zencoder::API.define_setting :audio_channels, :section => section do |z| z.tip = "The number of audio channels: 1 or 2." z.description = %Q{ <p>The number of audio channels to use: 1 (mono) or 2 (stereo).</p> <p>Note that mono AAC audio sometimes erroneously self-reports as stereo when inspected. We recommend using iTunes to get the true number of channels for AAC audio.</p> } z.data_type = "Integer" z.valid = "1 or 2" z.default = "1 if the original file is mono; otherwise, 2." z.example = "1" z.see_also = [:audio_bitrate, :audio_quality]end

Libraries

Support it

APIs are scary.

Make it fast

Rate limiting

loop { MyApi.create("data") }

Log requests

Request builder

GET /api/ideas

Competitive Advantage

1. Make friends

Awesomeness is noticed

(Assymetrical value curve)

value

quality

value

quality

value

quality

Bus Driving

quality

value

Bus Drivingvalue

quality

Sportsvalue

quality

API designvalue

quality

"I know the following statement is going to sound dramatic, but it's the truth. Zencoder seriously uplifted my entire day.

The API is really well designed and has documentation for not only what each value should be but also what an example input/output would look like using the value. I had spent the earlier part of the day working with a web service that is the complete opposite of those things.

So when I started digging into Zencoder I felt like I was witnessing a double rainbow. Then when I found the API Builder, it went beyond a double rainbow to a level I can only imagine is equal to witnessing a unicorn birth.”

2. Get rich

Software is eating the world

Software is eating the world

$0B

$50B

$100B

$150B

2010 2014

$148.8B

$68.3B

Cloud computing revenue forecast

Source: Gartner 2010

Need an idea?

API to

API to the government

API to your body

API to manufacturing

3. Change the world

In 2000...the cost of a customer running a basic Internet application was approximately $150,000 a month. Running that same application today in Amazon's cloud costs about $1,500 a month.

Mark Andreessen, “Why Software Is Eating The World”

1,000 CPU cores:

1,000 CPU cores:$204

50 phone numbers:

50 phone numbers:$50

POST /api/awesome_things HTTP/1.1

{ "team_size" : 3, "productivity" : "10x"}

Jon Dahl@jondahl

[email protected]