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


Published 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 20,000 developers.

Published in: Technology

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

  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