Top Banner
Advanced API Design How an awesome API can attract friends, make you rich, and change the world Jon Dahl @jondahl [email protected] Monday, May 23, 2011
103

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

Jul 15, 2015

Download

Technology

Jonathan Dahl
Welcome message from author
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Page 1: 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

Page 2: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

ApplicationProgrammingInterface

Monday, May 23, 2011

Page 3: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

UserInterface

Monday, May 23, 2011

Page 4: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Interface

Monday, May 23, 2011

Page 5: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

LibrarySDK

Monday, May 23, 2011

Page 6: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Net::SSH

Monday, May 23, 2011

Page 7: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Web Service

Monday, May 23, 2011

Page 8: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

SimpleObjectAccessProtocol

Monday, May 23, 2011

Page 9: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

SimpleObjectAccessProtocol

Monday, May 23, 2011

Page 10: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

REST

Monday, May 23, 2011

Page 11: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

HTTP

Monday, May 23, 2011

Page 12: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Web is an API

Monday, May 23, 2011

Page 13: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

GET /records

Monday, May 23, 2011

Page 14: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

POST /record/new

Monday, May 23, 2011

Page 15: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

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

Monday, May 23, 2011

Page 16: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

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

Monday, May 23, 2011

Page 17: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 18: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

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

Monday, May 23, 2011

Page 19: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 20: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 21: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

1. SecondaryFlickrTwitterLinkedinFacebook

Monday, May 23, 2011

Page 22: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

2. InfrastructureAmazon Web Services

EC2S3SQSRDSSNSSES

Monday, May 23, 2011

Page 23: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

3. TechnologyTwilioSimpleGeoSendgridZencoderFactualSpreedlyRecurlySaploTropoCloudMailinUploadJuicer

Monday, May 23, 2011

Page 24: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

4. Science FictionPiCloudCrowdflowerAmazon Mechanical Turk

Monday, May 23, 2011

Page 25: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 26: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 27: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 28: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

so, how do you design a good API?

Monday, May 23, 2011

Page 29: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Version it

Monday, May 23, 2011

Page 30: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

GET /api/records/38927

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

Monday, May 23, 2011

Page 31: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

GET /api/records/38927

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

Monday, May 23, 2011

Page 32: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

GET /api/v1/records/38927

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

Monday, May 23, 2011

Page 33: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

GET /api/v2/records/38927

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

Monday, May 23, 2011

Page 34: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

REST conventions

Monday, May 23, 2011

Page 35: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

GET POSTPUTDELETE

recordsjobsmessagesserversusers

Monday, May 23, 2011

Page 36: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

HTTP codes

Monday, May 23, 2011

Page 37: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

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

Monday, May 23, 2011

Page 38: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

... and many more!

Monday, May 23, 2011

Page 39: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Smart validations

Monday, May 23, 2011

Page 40: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

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

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

Monday, May 23, 2011

Page 41: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

HTTP/1.1 500 Internal Server Error

Monday, May 23, 2011

Page 42: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

HTTP/1.1 401 Unauthorized

Monday, May 23, 2011

Page 43: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

HTTP/1.1 401 Unauthorized

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

Monday, May 23, 2011

Page 44: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

HTTP/1.1 401 Unauthorized

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

Monday, May 23, 2011

Page 45: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

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

Monday, May 23, 2011

Page 46: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

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

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

Monday, May 23, 2011

Page 47: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

HTTP/1.1 400 Bad Request

Monday, May 23, 2011

Page 48: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

HTTP/1.1 400 Bad Request

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

Monday, May 23, 2011

Page 49: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

JSON + XML

Monday, May 23, 2011

Page 50: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 51: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 52: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

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

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

Monday, May 23, 2011

Page 53: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

params[:strength] # 18

Monday, May 23, 2011

Page 54: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

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

Monday, May 23, 2011

Page 55: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Document it

Monday, May 23, 2011

Page 56: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

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

Monday, May 23, 2011

Page 57: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 58: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Libraries

Monday, May 23, 2011

Page 59: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Support it

Monday, May 23, 2011

Page 60: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

APIs are scary.

Monday, May 23, 2011

Page 61: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Make it fast

Monday, May 23, 2011

Page 62: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Rate limiting

Monday, May 23, 2011

Page 63: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Log requests

Monday, May 23, 2011

Page 64: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 65: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 66: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Request builder

Monday, May 23, 2011

Page 67: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 68: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 69: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

GET /api/ideas

Monday, May 23, 2011

Page 70: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

1. Make friends

Monday, May 23, 2011

Page 71: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 72: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Awesomeness is noticed

Monday, May 23, 2011

Page 73: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

(Assymetrical reward curve)

Monday, May 23, 2011

Page 74: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

value

quality

Monday, May 23, 2011

Page 75: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

value

quality

Monday, May 23, 2011

Page 76: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

value

quality

Monday, May 23, 2011

Page 77: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Bus Driving

quality

value

Monday, May 23, 2011

Page 78: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Bus Drivingvalue

quality

Monday, May 23, 2011

Page 79: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 80: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Sportsvalue

quality

Monday, May 23, 2011

Page 81: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

API designvalue

quality

Monday, May 23, 2011

Page 82: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

"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.”

Monday, May 23, 2011

Page 83: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

2. Get rich

Monday, May 23, 2011

Page 84: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

$0B

$50B

$100B

$150B

2010 2014

$148.8B

$68.3B

Cloud computing revenue forecast

Source: Gartner 2010

Monday, May 23, 2011

Page 85: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

4.TwilioSimpleGeoSendgridZencoderFactualSpreedlyRecurlySaploTropoCloudMailinUploadJuicer

Monday, May 23, 2011

Page 86: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

API to

Monday, May 23, 2011

Page 87: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

API to Ruby

Monday, May 23, 2011

Page 88: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

API to the government

Monday, May 23, 2011

Page 89: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

API to manufacturing

Monday, May 23, 2011

Page 90: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

3. Change the world

Monday, May 23, 2011

Page 91: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 92: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 93: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 94: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 95: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 96: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 97: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 98: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 99: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 100: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 101: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Monday, May 23, 2011

Page 102: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

POST /api/awesome_things HTTP/1.1

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

Monday, May 23, 2011

Page 103: Advanced API Design: how an awesome API can attract friends, make you rich, and change the world

Jon Dahl@jondahl

[email protected]

Thanks!

Monday, May 23, 2011