Download as PDF, PPTX
Uploaded byTwilio Inc
Building a Great Web API - Evan Cooke - QCON 2011
Evan Cooke discusses best practices for building efficient web APIs, emphasizing that developers should be able to complete a useful task within five minutes of first use. Key principles include clear value propositions, simple and self-documenting APIs, and adherence to RESTful design that supports versioning and idempotency. The document also highlights the importance of responsive and predictable APIs, as well as effective deployment practices within Twilio's infrastructure.
More Related Content
![Influencer Marketing Plan [template]](https://cdn.slidesharecdn.com/ss_thumbnails/influencer-marketing-plan-for-2016-template-1-160215170708-thumbnail.jpg?width=640&height=640&fit=bounds)
Similar to Building a Great Web API - Evan Cooke - QCON 2011
![Coded Agents – with UiPath SDK + LangGraph [Virtual Hands-on Workshop]](https://cdn.slidesharecdn.com/ss_thumbnails/codedagentsdeck-251215155422-5497c599-thumbnail.jpg?width=640&height=640&fit=bounds)
Building a Great Web API - Evan Cooke - QCON 2011
- 1. BUILDING A GREAT WEBAPI NOVEMBER 17, 2011, QCON T P EVAN COOKE @emcooke H T CO-FOUNDER & CTO twilio CLOUD COMMUNICATIONS
- 2. One simple goal forbuilding great Web APIs...
- 3.
- 4. It should takeno more than 5 minutes for a developer to perform a useful task using your API for the first time
- 5. What is aWeb API? Definition for today: • HTTP/HTTPS endpoint • JSON/XML • Hosted API/Web service • Example: Amazon S3
- 7. Twilio Web service APIs to automate Voice and SMS phone communications Carriers Inbound Calls Voice Outbound Calls Mobile/Browser VoIP Send To/From Phone SMS Numbers Short Codes Developer Phone Dynamically Buy Numbers Phone Numbers End User
- 9. Why 5 Minutes? •Clear value proposition • Fast signup • Simple API • Efficient quickstarts • Concise accessible docs • Easy authentication (basic vs. oauth) • Debuggable
- 10. API Adoption Funnel Hearabout API Good APIs Try it Promote Adoption (tell friends) Build it Production Use Buy it Traction
- 11. API Adoption Funnel Hearabout API Try it 5-Minute Goal Build it Production Use Buy it Traction
- 12. 5-minute APIs APIDesign
- 13. Co un te rE 5-minute APIs xa API Design m ple
- 14. Media processing API • HTTP API to analyze large (MBs) media files • High tps ~100,000/day • POST data to the API You Media API • Analysis API synchronously returns analysis of media (could be minutes/hours later)
- 15. 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
- 16. 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 Problem Can we safely retry the request on a transient failure?
- 17. 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 Problem Exposed to transient failures if the processing takes minutes/hours?
- 18. 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 Problem Request is huge and fragile when data is included with control cmd?
- 19. 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
- 20. 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
- 21. 5-minute APIs APIDesign
- 22. 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/Funds {‘value’: 1000, ‘token’: ‘TX123’}
- 24. Self-documentation • Sweat whatand how you name. Naming is is the best documentation. • Example: GET /Users/ID123 GET /Users/ID123/Friends GET /Users/ID123/Photos
- 26. 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
- 28. Versioning • Do it.Remember you will be stuck supporting old API versions (indefinitely?) • Examples GET /api/1/blag GET /api/v1/blag GET /api/20101206/blag
- 30. 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
- 32. Predictability • The APIshould do what users expect • Examples <Play>music.mp3</Play> <Play>music.aiff</Play>
- 34. Responsiveness • When aresponse 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
- 36. Key Ideas • Idempotency • Self-documentation • RESTfulness • Versioning • Statefulness • Predictability • Responsiveness
- 37. 5-minute APIs “Good”
- 38. 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 Bloch, Google
- 39.
- 41. Saleforce auth Campaigns from Adword API
- 42. Dynamic phone number provisioningvia Twilio API
- 43. Saleforce CRM data Saleforce app APIs Google Maps API Twilio Client API
- 45.
- 46. DEPLOYING YOUR WEB API T P H T twilio CLOUD COMMUNICATIONS
- 47. Infrastructure • 100’s ofprod hosts in continuous operation • 80+ service types running in prod - Python(Twisted/GEvent), PHP, Java • 50+ prod database servers - MySQL, Redis • Prod deployments several times/day across 7 engineering teams
- 48. Website Deployment Content Frequency(Risk) 4 buckets Website Code Log Scale 1000x REST API Big DB 100x Schema 10x 1x CMS PHP/Ruby Python/Java SQL etc. etc.
- 49. Website Deployment Content Processes Website Code REST API Big DB Schema One Click CI Tests CI Tests CI Tests One Click Human Sign-off Human Sign-off One Click Human Assisted Click
- 50. Cluster automation viaboxconfig
- 51. Cluster automation viaboxconfig • Build and deployment system - boot entire Twilio stack with one key press • Host configuration - versioned code & config • Host orchestration - load balancing • Monitoring and alerting - nagios • Multi-datacenter deployment & analytics
- 52. Cluster automation viaboxconfig role role role Start Roles Fetch Provision S3 SVN/git Boxconfig Base (AMI) Vanilla Linux Host (cloud/colo)
- 53. twilio Evan Cooke @emcooke