Building A Great API - Evan Cooke, Cloudstock, December 2010

Uploaded on

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 …

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.

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads


Total Views
On Slideshare
From Embeds
Number of Embeds



Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

    No notes for slide


  • 2. Why make Great APIs? Hear about API Good APIs Promote Adoption Use in production (tell friends)
  • 3. Today’s discussion focuseson APIs exposed by Internetservices, however, the ideaswe discuss can be applied in many contexts
  • 4. Where Do APIs Come From?• APIs that have grown from products End Users Facebook API API API
  • 5. Where Do APIs Come From?• APIs that are the product End Users Developers Cloud API
  • 6. Twilio Web service APIs to automate Voice and SMS communications Phone Voice SMS Numbers Inbound Calls To/From Phone APIs toOutbound Calls Numbers Dynamically IVR Short Codes Provision Phone Numbers
  • 7. Outline1. Case Studies2. Design3. Presentation4. Development
  • 8. Case Studies
  • 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 API1 Original Request POST key=2hkh&mode=bob&filter=yeah Body is 100MB of binary data
  • 13. Media processing API2 Add a token allowing us to safely retry POST key=2hkh&mode=bob&filter=yeah&token=TK123 Body is 100MB of binary data
  • 14. Media processing API3 Add webhook url to asynchronously respond POST key=2hkh&mode=bob&filter=yeah&token=TK123&c Body is 100MB of binary data
  • 15. Media processing API4 Async fetch media & move POST params to body POST Body key=2hkh mode=bob filter=yeah token=TK123 cbUrl= mediaUrl=
  • 16. Media processing API5 Version API and make URL more RESTful POST Body key=2hkh mode=bob filter=yeah token=TK123 cbUrl= mediaUrl= Response URI
  • 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
  • 19. Design
  • 20. Key Ideas• Idempotency• Self-documenting• RESTfulness• Versioning• Statefulness• Predictability• Sync vs. Async
  • 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/ID123GET /Users/ID123/FriendsGET /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!• ExamplesPOST /CallsGET /Calls/CA123GET /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/TransformsBody cbUrl=
  • 28. Presentation
  • 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
  • 32. Wufoo• Simple well- documented REST API• Good use of HTTP verbs and errors
  • 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
  • 34. Easy to Learn
  • 35. Easy to Use
  • 36. Easy to read/maintain code HTTP/XML/JSON REST Customer Telecom Business Goo Logic
  • 37. Sufficiently PowerfulIt sure helps to write code live if you are pitching todevelopers. John got a big nod from the audience for doingthat.But the important point is that when you show your productlive in front of people, they can get what you are doing wayfaster than working through a bunch of slides. Kudos to Johnfor an excellent pitch. Apparently Business Insider called it"the best demo weve ever seen.
  • 38. Easy to extend Expose Twilio in an async evented model
  • 39. Development
  • 40. Twilio Process1. Customers Feedback2. Documentation3. Team feedback (back to 2)4. Prototype (2-3 weeks)5. Alpha customers6. Preview Customers7. General Release
  • 41. Design Idempotent, self-documenting, RESTful, versioned, stateful, predictable, sync/asyncPresentation Easy to learn, easy to use, easy to read and maintainable, sufficiently powerful, easy to extendDevelopment Customers, documentation, team, prototype, alpha customers, preview customers, release
  • 42. Be Simple
  • 43. twilio @emcooke