Building A Great API - Evan Cooke, Cloudstock, December 2010
27 likes6,478 views
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.
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 Great APIs? Hear about API Good APIs Promote Adoption Use in production (tell friends)
- 3. Today’s discussion focuses on APIs exposed by Internet services, however, the ideas we 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 to Outbound Calls Numbers Dynamically IVR Short Codes Provision Phone Numbers
- 7. Outline 1. Case Studies 2. Design 3. Presentation 4. 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 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=https%3A%2F%2Fblue-sea-697d.quartiers047.workers.dev%3A443%2Fhttp%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
- 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/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
- 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 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. Development
- 40. Twilio Process 1. Customers Feedback 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. Be Simple