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

1,651 views
1,567 views

Published on

Published in: Technology
0 Comments
3 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,651
On SlideShare
0
From Embeds
0
Number of Embeds
68
Actions
Shares
0
Downloads
28
Comments
0
Likes
3
Embeds 0
No embeds

No notes for slide

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

  1. 1. Advanced API Design How an awesome API can attract friends, make you rich, and change the world Jon Dahl @jondahl jon@zencoder.com
  2. 2. ApplicationProgrammingInterface
  3. 3. UserInterface
  4. 4. Interface
  5. 5. LibrarySDK
  6. 6. Net::SSH
  7. 7. Web Service
  8. 8. SimpleObjectAccessProtocol
  9. 9. SimpleObjectAccessProtocol
  10. 10. REST
  11. 11. HTTP
  12. 12. Web is an API
  13. 13. GET /records
  14. 14. POST /record/new
  15. 15. POST /record/new<xml> <data>Foo</data></xml>
  16. 16. POST /record/new{ "data" : "foo"}
  17. 17. (Don’t tell our investors thatwe don’t have a real product)
  18. 18. Some Examples
  19. 19. 1. Second InterfaceFlickrTwitterLinkedinFacebookPaypalGoogle Maps
  20. 20. 2. Internal APIsService Oriented ArchitectureMobile application backends
  21. 21. 3. Core TechAmazon Web ServicesTwilioGeoloqiZencoderSendgridFactualSpreedlyRecurlySaploTropo
  22. 22. 4. Science FictionPiCloudAmazon Mechanical Turk...
  23. 23. so, how do you design a good API?
  24. 24. CompetitiveAdvantage
  25. 25. REST conventions
  26. 26. GET recordsPOST jobsPUT messagesDELETE servers users
  27. 27. HTTP codes
  28. 28. 200 OK201 Created202 Accepted400 Bad Request401 Unauthorized402 Payment Required404 Not Found409 Conflict418 I’m a teapot422 Unprocessable Entity500 Internal Server Error503 Service Unavailable
  29. 29. ... and many more!
  30. 30. Version it
  31. 31. GET /api/records/38927{ "color" : "green", "velocity" : 1000000}
  32. 32. GET /api/records/38927{ "color" : "10EE33", "velocity" : 1000000}
  33. 33. GET /api/v1/records/38927{ "color" : "green", "velocity" : 1000000}
  34. 34. GET /api/v2/records/38927{ "color" : "10EE33", "velocity" : 1000000}
  35. 35. GET /api/records/38927?version=2GET /api/v2/records/38927GET /api/records/38927Accept: application/json+v2
  36. 36. Smart validations
  37. 37. POST /api/jobs HTTP/1.1Accept: application/jsonContent-Type: application/json{ "api_key" : "Not A Real Key", "color" : "green"}
  38. 38. HTTP/1.1 500 Internal Server Error
  39. 39. HTTP/1.1 401 Unauthorized
  40. 40. HTTP/1.1 401 Unauthorized{ "errors": [ "api_key not found" ]}
  41. 41. HTTP/1.1 401 Unauthorized{ "errors": [ "api_key not found.", "api_key may not include spaces." ]}
  42. 42. 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." ]}
  43. 43. POST /api/user HTTP/1.1Accept: application/jsonContent-Type: application/json{ "api_key" : "A23B92F281CC" "strength" : 18}
  44. 44. HTTP/1.1 400 Bad Request
  45. 45. HTTP/1.1 400 Bad Request{ "errors": [ "JSON is not valid. Syntax error,unexpected TSTRING, expecting }at line 2" ]}
  46. 46. JSON + XML
  47. 47. POST /api/user HTTP/1.1Accept: application/jsonContent-Type: application/json{ "api_key" : "A23B92F281CC", "strength" : 18}
  48. 48. params[:strength] # 18
  49. 49. respond_to do |wants| wants.json { render :json => @jobs.to_json } wants.xml { render :xml => @jobs.to_xml }end
  50. 50. Document it
  51. 51. 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
  52. 52. Libraries
  53. 53. Support it
  54. 54. APIs are scary.
  55. 55. Make it fast
  56. 56. Rate limiting
  57. 57. loop { MyApi.create("data") }
  58. 58. Log requests
  59. 59. Request builder
  60. 60. GET /api/ideas
  61. 61. CompetitiveAdvantage
  62. 62. 1. Make friends
  63. 63. Awesomeness is noticed
  64. 64. (Assymetrical value curve)
  65. 65. valuequality
  66. 66. valuequality
  67. 67. valuequality
  68. 68. Bus Driving value quality
  69. 69. Bus Driving value quality
  70. 70. Sports valuequality
  71. 71. API design value quality
  72. 72. "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.”
  73. 73. 2. Get rich
  74. 74. Software is eatingthe world
  75. 75. Software is eatingthe world
  76. 76. Cloud computing revenue forecast$150B $148.8B$100B $68.3B $50B $0B 2010 2014 Source: Gartner 2010
  77. 77. Need an idea?
  78. 78. API to
  79. 79. API tothe government
  80. 80. API toyour body
  81. 81. API tomanufacturing
  82. 82. 3. Change the world
  83. 83. 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”
  84. 84. 1,000 CPU cores:
  85. 85. 1,000 CPU cores:$204
  86. 86. 50 phone numbers:
  87. 87. 50 phone numbers:$50
  88. 88. POST /api/awesome_things HTTP/1.1{ "team_size" : 3, "productivity" : "10x"}
  89. 89. Jon Dahl @jondahljon@zencoder.com

×