![HTTP/1.1 401 Unauthorized
{
"errors": [
"api_key not found"
]
}](https://image.slidesharecdn.com/advancedapidesignshort-120312100010-phpapp02/85/Advanced-API-Design-how-an-awesome-API-can-help-you-make-friends-get-rich-and-change-the-world-46-320.jpg)
![HTTP/1.1 401 Unauthorized
{
"errors": [
"api_key not found.",
"api_key may not include spaces."
]
}](https://image.slidesharecdn.com/advancedapidesignshort-120312100010-phpapp02/85/Advanced-API-Design-how-an-awesome-API-can-help-you-make-friends-get-rich-and-change-the-world-47-320.jpg)
![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."
]
}](https://image.slidesharecdn.com/advancedapidesignshort-120312100010-phpapp02/85/Advanced-API-Design-how-an-awesome-API-can-help-you-make-friends-get-rich-and-change-the-world-48-320.jpg)
![HTTP/1.1 400 Bad Request
{
"errors": [
"JSON is not valid. Syntax error,
unexpected TSTRING, expecting '}'
at line 2"
]
}](https://image.slidesharecdn.com/advancedapidesignshort-120312100010-phpapp02/85/Advanced-API-Design-how-an-awesome-API-can-help-you-make-friends-get-rich-and-change-the-world-51-320.jpg)
![params[:strength] # 18](https://image.slidesharecdn.com/advancedapidesignshort-120312100010-phpapp02/85/Advanced-API-Design-how-an-awesome-API-can-help-you-make-friends-get-rich-and-change-the-world-56-320.jpg)
![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](https://image.slidesharecdn.com/advancedapidesignshort-120312100010-phpapp02/85/Advanced-API-Design-how-an-awesome-API-can-help-you-make-friends-get-rich-and-change-the-world-59-320.jpg)
Advanced API Design: how an awesome API can help you make friends, get rich, and change the world
- 1. Advanced API Design How an awesome API can attract friends, make you rich, and change the world Jon Dahl @jondahl jon@zencoder.com
- 5. Interface
- 6. Library SDK
- 7. Net::SSH
- 8. Web Service
- 11. REST
- 12. HTTP
- 13. Web is an API
- 14. GET /records
- 15. POST /record/new
- 17. POST /record/new { "data" : "foo" }
- 19. (Don’t tell our investors that we don’t have a real product)
- 21. Some Examples
- 23. 2. Internal APIs Service Oriented Architecture Mobile application backends
- 24. 3. Core Tech Amazon Web Services Twilio Geoloqi Zencoder Sendgrid Factual Spreedly Recurly Saplo Tropo
- 25. 4. Science Fiction PiCloud Amazon Mechanical Turk ...
- 26. so, how do you design a good API?
- 31. REST conventions
- 32. GET records POST jobs PUT messages DELETE servers users
- 33. HTTP codes
- 34. 200 OK 201 Created 202 Accepted 400 Bad Request 401 Unauthorized 402 Payment Required 404 Not Found 409 Conflict 418 I’m a teapot 422 Unprocessable Entity 500 Internal Server Error 503 Service Unavailable
- 35. ... and many more!
- 36. Version it
- 37. GET /api/records/38927 { "color" : "green", "velocity" : 1000000 }
- 38. GET /api/records/38927 { "color" : "10EE33", "velocity" : 1000000 }
- 39. GET /api/v1/records/38927 { "color" : "green", "velocity" : 1000000 }
- 40. GET /api/v2/records/38927 { "color" : "10EE33", "velocity" : 1000000 }
- 41. GET /api/records/38927?version=2 GET /api/v2/records/38927 GET /api/records/38927 Accept: application/json+v2
- 43. POST /api/jobs HTTP/1.1 Accept: application/json Content-Type: application/json { "api_key" : "Not A Real Key", "color" : "green" }
- 44. HTTP/1.1 500 Internal Server Error
- 46. HTTP/1.1 401 Unauthorized { "errors": [ "api_key not found" ] }
- 47. HTTP/1.1 401 Unauthorized { "errors": [ "api_key not found.", "api_key may not include spaces." ] }
- 48. 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." ] }
- 49. POST /api/user HTTP/1.1 Accept: application/json Content-Type: application/json { "api_key" : "A23B92F281CC" "strength" : 18 }
- 50. HTTP/1.1 400 Bad Request
- 51. HTTP/1.1 400 Bad Request { "errors": [ "JSON is not valid. Syntax error, unexpected TSTRING, expecting '}' at line 2" ] }
- 52. JSON + XML
- 55. POST /api/user HTTP/1.1 Accept: application/json Content-Type: application/json { "api_key" : "A23B92F281CC", "strength" : 18 }
- 57. respond_to do |wants| wants.json { render :json => @jobs.to_json } wants.xml { render :xml => @jobs.to_xml } end
- 58. Document it
- 59. 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
- 61. Libraries
- 62. Support it
- 63. APIs are scary.
- 64. Make it fast
- 65. Rate limiting
- 67. Log requests
- 70. Request builder
- 73. GET /api/ideas
- 75. 1. Make friends
- 79. value quality
- 80. value quality
- 81. value quality
- 82. Bus Driving value quality
- 83. Bus Driving value quality
- 85. Sports value quality
- 86. API design value quality
- 87. "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.”
- 88. 2. Get rich
- 89. Software is eating the world
- 90. Software is eating the world
- 91. Cloud computing revenue forecast $150B $148.8B $100B $68.3B $50B $0B 2010 2014 Source: Gartner 2010
- 92. Need an idea?
- 93. API to
- 95. API to your body
- 97. 3. Change the world
- 100. 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”
- 110. 1,000 CPU cores:
- 112. 50 phone numbers:
- 114. POST /api/awesome_things HTTP/1.1 { "team_size" : 3, "productivity" : "10x" }
- 119. Jon Dahl @jondahl jon@zencoder.com