Tips and tricks on how to design, package, and build a great API. We summarize some of the lessons we've learned over the years at Twilio designing and operating Voice and SMS APIs used by more then 20,000 developers.
9. What NOT to Do
• Media processing API Vendor
• Telecom API
10. Media processing API
• HTTP API to analyze large
media files
• Tx Rate 100,000/day
(costly) Media
• POST data to the API You Analysis API
• API synchronously returns
analysis of media (could
be minutes/hours later)
11. Media processing API
• Control and data in the
same request (100 MB
every request)
• Unclear error conditions.
Can you resend request? You API
• Synchronously wait for ???
response
• No request history/billing
information
12. Media processing API
1 Original Request
POST http://api.vendor.com/API/Process?
key=2hkh&mode=bob&filter=yeah
Body is 100MB of binary data
13. Media processing API
2 Add a token allowing us to safely retry
POST http://api.vendor.com/API/Process?
key=2hkh&mode=bob&filter=yeah&token=TK123
Body is 100MB of binary data
14. Media processing API
3 Add webhook url to asynchronously respond
POST http://api.vendor.com/API/Process?
key=2hkh&mode=bob&filter=yeah&token=TK123&c
bUrl=http%3A%2F%2Fmyserver.com%2Fresponse
Body is 100MB of binary data
15. Media processing API
4 Async fetch media & move POST params to body
POST http://api.vendor.com/API/Process
Body
key=2hkh
mode=bob
filter=yeah
token=TK123
cbUrl=http://myserver.com/response
mediaUrl=http://s3.com/media.mov
16. Media processing API
5 Version API and make URL more RESTful
POST http://api.vendor.com/v1/Media
Body
key=2hkh
mode=bob
filter=yeah
token=TK123
cbUrl=http://myserver.com/response
mediaUrl=http://s3.com/media.mov
Response
URI http://api.vendor.com/v1/Media/MD123
17. What NOT to Do
• Media processing API Vendor
• Telecom API
18. Telecom API
• API to manage phone numbers
• Documentation is 300 page PDF,
pages of WSDL
• 95% useless RPC functions that
expose internal business logic
• No simple way to get started
• No helper libraries
21. Idempotency
• Idempotence is the property of certain
operations that they can be applied multiple
times without changing the result.
• Request failures happen. Provide users a
safe way to retry requests
• Example:
POST /BankAccount/AddFunds
{‘value’: 1000, ‘token’: ‘TX123’}
22. Self-documenting
• Sweat what and how you name. Naming is
is the best documentation.
• Example:
GET /Users/ID123
GET /Users/ID123/Friends
GET /Users/ID123/Photos
23. RESTfulness
• Adherence to REST object model and
verbs provides a clean way to expose
business logic
• Create POST /Users
• Fetch GET /Users/ID123
• Modify PUT/POST /Users/ID123
• Remove DELETE /Users/ID123
24. Versioning
• Do it. Remember you will be stuck
supporting old API versions (indefinitely?)
• Examples
GET /api/v1/blag
GET /api/20101206/blag
25. Statefulness
• When possible, offload the work of keeping
state/history because it’s hard!
• Examples
POST /Calls
GET /Calls/CA123
GET /Calls/CA123/Recordings/RE123
26. Predictability
• The API should do what users expect
• Examples
<Play>music.mp3</Play>
<Play>music.aiff</Play>
27. Sync vs Async
• When a response is available immediately,
use a synchronous response. Otherwise,
consider an asynchronous Webhook rather
then polling
• Examples:
POST /Object/Transforms
Body
cbUrl=http://b.com/response
29. Great APIs
• Redis - Key/Value, List, and Set Persistence
• Dropbox - REST, iOS/Android File Mgnt
• Wufoo - Web forms
Other Notable APIs
SimpleGeo, Github, Posterous, Tumblr,
Facebook... great, but getting to their docs requires
authenticating!
30. Redis
• Simple, well
named API calls
• Powerful
• APIs that cover
major operational
tasks
31. Dropbox
• API support
across platforms/
languages
• Community
integration
33. What makes a Good API?
• Easy to Learn
• Easy to use (even without documentation)
• Hard to Misuse
• Easy to read and maintain code that uses it
• Sufficiently powerful to satisfy requirements
• Easy to extend
• Appropriate to audience
How to Design a Good API and Why it Matters
Joshua Block, Google
37. Sufficiently
Powerful
It sure helps to write code live if you are pitching to
developers. John got a big nod from the audience for doing
that.
But the important point is that when you show your product
live in front of people, they can get what you are doing way
faster than working through a bunch of slides. Kudos to John
for an excellent pitch. Apparently Business Insider called it
"the best demo we've ever seen.