Download as PDF, PPTX
Uploaded byTwilio Inc
Building A Great API - Evan Cooke, Cloudstock, December 2010
The document discusses the importance of creating great APIs and outlines key design principles such as idempotency, self-documenting, and RESTfulness. It also highlights common pitfalls in existing APIs, particularly in media processing and telecom services, while providing case studies to illustrate best practices. Lastly, it emphasizes the significance of customer feedback and iterative development in building effective APIs.
More Related Content
Similar to Building A Great API - Evan Cooke, Cloudstock, December 2010
Building A Great API - Evan Cooke, Cloudstock, December 2010
- 1. twilio CLOUD COMMUNICATIONS BUILDING A GREAT API DECEMBER 6, 2010, CLOUDSTOCK EVAN COOKE
- 2. Why make GreatAPIs? Hear about API Good APIs Promote Adoption Use in production (tell friends)
- 3. Today’s discussion focuses onAPIs exposed by Internet services, however, the ideas we discuss can be applied in many contexts
- 4. Where Do APIsCome From? • APIs that have grown from products End Users Facebook API API API
- 5. Where Do APIsCome 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 to Outbound Calls Numbers Dynamically IVR Short Codes Provision Phone Numbers
- 7. Outline 1. Case Studies 2.Design 3. Presentation 4. Development
- 8.
- 9. What NOT toDo • 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 toDo • 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.
- 20. Key Ideas • Idempotency • Self-documenting • RESTfulness • Versioning • Statefulness • Predictability • Sync vs. Async
- 21. Idempotency • Idempotence isthe 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 whatand how you name. Naming is is the best documentation. • Example: GET /Users/ID123 GET /Users/ID123/Friends GET /Users/ID123/Photos
- 23. RESTfulness • Adherence toREST 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 APIshould 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
- 28.
- 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 aGood 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.
- 35.
- 36. Easy to read/maintaincode HTTP/XML/JSON REST Customer Telecom Business Goo Logic
- 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.
- 38. Easy to extend Expose Twilio in an async evented model
- 39.
- 40. Twilio Process 1. CustomersFeedback 2. Documentation 3. Team feedback (back to 2) 4. Prototype (2-3 weeks) 5. Alpha customers 6. Preview Customers 7. General Release
- 41. Design Idempotent,self-documenting, RESTful, versioned, stateful, predictable, sync/async Presentation Easy to learn, easy to use, easy to read and maintainable, sufficiently powerful, easy to extend Development Customers, documentation, team, prototype, alpha customers, preview customers, release
- 42.
- 43. twilio http://www.twilio.com @emcooke