advanced api design: how an awesome api can help you make friends, get rich, and change the world
DESCRIPTION
TRANSCRIPT
Advanced API DesignHow an awesome API can
attract friends, make you rich,
and change the world
Jon Dahl@jondahl
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