Advanced API Design: how an awesome API can attract friends, make you 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]

Monday, May 23, 2011

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)




1. SecondaryFlickrTwitterLinkedinFacebook


2. InfrastructureAmazon Web Services

EC2S3SQSRDSSNSSES


3. TechnologyTwilioSimpleGeoSendgridZencoderFactualSpreedlyRecurlySaploTropoCloudMailinUploadJuicer


4. Science FictionPiCloudCrowdflowerAmazon Mechanical Turk





so, how do you design a good API?


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}


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!


Smart validations


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

{ "api_key" : "Not A Real Key"}


HTTP/1.1 500 Internal Server Error


HTTP/1.1 401 Unauthorized



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



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



{ "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." ]}


https://example.com/account/api




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


Log requests




Request builder




GET /api/ideas


1. Make friends



Awesomeness is noticed


(Assymetrical reward 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


$0B

$50B

$100B

$150B

2010 2014

$148.8B

$68.3B

Cloud computing revenue forecast

Source: Gartner 2010


4.TwilioSimpleGeoSendgridZencoderFactualSpreedlyRecurlySaploTropoCloudMailinUploadJuicer


API to


API to Ruby


API to the government


API to manufacturing


3. Change the world













POST /api/awesome_things HTTP/1.1

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


Jon Dahl@jondahl

[email protected]

Thanks!
