Advanced API Design: how an awesome API can help you make friends, get rich, and change the world
Upcoming SlideShare
Loading in...5
×
 

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

on

  • 1,517 views

 

Statistics

Views

Total Views
1,517
Slideshare-icon Views on SlideShare
1,460
Embed Views
57

Actions

Likes
2
Downloads
23
Comments
0

4 Embeds 57

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

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    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 help you make friends, get rich, and change the world Presentation Transcript

    • 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
    • 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 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 Conflict418 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
    • valuequality
    • valuequality
    • Bus Driving value quality
    • 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
    • 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