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

Advanced API Design How an awesome API can attract friends, make you rich, and change the world Jon Dahl @jondahl jon@zencoder.com

ApplicationProgrammingInterface

UserInterface

Interface

LibrarySDK

Net::SSH

Web Service

SimpleObjectAccessProtocol

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 thatwe don’t have a real product)

Some Examples

1. Second InterfaceFlickrTwitterLinkedinFacebookPaypalGoogle Maps

2. Internal APIsService Oriented ArchitectureMobile application backends

3. Core TechAmazon Web ServicesTwilioGeoloqiZencoderSendgridFactualSpreedlyRecurlySaploTropo

4. Science FictionPiCloudAmazon Mechanical Turk...

so, how do you design a good API?

CompetitiveAdvantage

REST conventions

GET recordsPOST jobsPUT messagesDELETE servers users

HTTP codes

200 OK201 Created202 Accepted400 Bad Request401 Unauthorized402 Payment Required404 Not Found409 Conﬂict418 I’m a teapot422 Unprocessable Entity500 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=2GET /api/v2/records/38927GET /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 APIkey.", "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 => sectiondo |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-reportsas stereo when inspected. We recommend using iTunes to get the truenumber 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

CompetitiveAdvantage

1. Make friends

Awesomeness is noticed

(Assymetrical value curve)

valuequality

Bus Driving value quality

Sports valuequality

API design value quality

"I know the following statement is going to sound dramatic,but its the truth. Zencoder seriously uplifted my entire day.The API is really well designed and has documentation for notonly what each value should be but also what an exampleinput/output would look like using the value. I had spent theearlier part of the day working with a web service that is thecomplete opposite of those things.So when I started digging into Zencoder I felt like I waswitnessing a double rainbow. Then when I found the APIBuilder, it went beyond a double rainbow to a level I can onlyimagine is equal to witnessing a unicorn birth.”

2. Get rich

Software is eatingthe world

Cloud computing revenue forecast$150B $148.8B$100B $68.3B $50B $0B 2010 2014 Source: Gartner 2010

Need an idea?

API to

API tothe government

API toyour body

API tomanufacturing

3. Change the world

In 2000...the cost of a customer running a basicInternet application was approximately $150,000a month. Running that same application today inAmazons 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 @jondahljon@zencoder.com

http://lanyrd.com	40
http://bo.lt	7
http://stg.lanyrd.org	1
http://bundlr.com	1

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

by Jonathan Dahl on Mar 12, 2012

Accessibility

Categories

Upload Details

Usage Rights

4 Embeds 49

Statistics

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