BUILDING AGREAT WEB APINOVEMBER 17, 2011, QCON                                  T PEVAN COOKE @emcooke                    ...
One simple goalfor building great    Web APIs...
5Minutes
It should take no more  than 5 minutes for adeveloper to perform a useful task using your  API for the first time
What is a Web API?Definition for today:• HTTP/HTTPS endpoint• JSON/XML• Hosted API/Web service• Example: Amazon S3
Twilio   Web service APIs to automate Voice and        SMS phone communications Carriers                      Inbound Call...
Why 5 Minutes?• Clear value proposition• Fast signup• Simple API• Efficient quickstarts• Concise accessible docs• Easy auth...
API Adoption FunnelHear about API                 Good APIs                     Try it     Promote                        ...
API Adoption FunnelHear about API       Try it    5-Minute                                 Goal                    Build i...
5-minute APIs API Design
Co  un     te        rE   5-minute APIs          xa    API Design             m                ple
Media processing API•   HTTP API to analyze large    (MBs) media files•   High tps ~100,000/day•   POST data to the API    ...
Media processing API•   Control and data in the    same request (100 MB    every request)•   Unclear error conditions.    ...
Media processing API1   Original Request    POST http://api.vendor.com/API/Process?    key=2hkh&mode=bob&filter=yeah    Bo...
Media processing API2   Add a token allowing us to safely retry    POST http://api.vendor.com/API/Process?    key=2hkh&mod...
Media processing API3   Add webhook url to asynchronously respond    POST http://api.vendor.com/API/Process?    key=2hkh&m...
Media processing API4   Async fetch media & move POST params to body    POST http://api.vendor.com/API/Process    Body    ...
Media processing API5   Version API and make URL more RESTful    POST http://api.vendor.com/v1/Media    Body       key=2hk...
5-minute APIs API Design
Idempotency• Idempotence is the property of certain  operations that they can be applied multiple  times without changing ...
Self-documentation• Sweat what and how you name. Naming is  is the best documentation.• Example:GET /Users/ID123GET /Users...
RESTfulness• Adherence to REST object model and  verbs provides a clean way to expose  business logic• Create POST        ...
Versioning• Do it. Remember you will be stuck  supporting old API versions (indefinitely?)• Examples  GET /api/1/blag  GET ...
Statefulness• When possible, offload the work of keeping  state/history because it’s hard!• ExamplesPOST /CallsGET /Calls/C...
Predictability• The API should do what users expect• Examples  <Play>music.mp3</Play>  <Play>music.aiff</Play>
Responsiveness• When a response is available immediately,  use a synchronous response. Otherwise,  consider an asynchronou...
Key Ideas•   Idempotency•   Self-documentation•   RESTfulness•   Versioning•   Statefulness•   Predictability•   Responsiv...
5-minute APIs   “Good”
What makes a good API? • Easy to Learn • Easy to use (even without documentation) • Hard to Misuse • Easy to read and main...
Human-centric
Saleforce  auth      Campaigns from             Adword API
Dynamic phone numberprovisioning via Twilio API
SaleforceCRM data                   Saleforce                   app APIs GoogleMaps API            Twilio Client API
Simplicity
DEPLOYINGYOUR WEBAPI                               T P                         H                           T  twilio  CLOU...
Infrastructure• 100’s of prod hosts in continuous operation• 80+ service types running in prod - Python(Twisted/GEvent), P...
Website                 Deployment            Content                                 Frequency(Risk)                     ...
Website                        DeploymentContent                                 Processes             Website            ...
Cluster automation via boxconfig
Cluster automation via boxconfig• Build and deployment system - boot entire  Twilio stack with one key press• Host configura...
Cluster automation via boxconfig             role role role      Start Roles     Fetch                    ProvisionS3      ...
twilio Evan Cooke @emcooke
Building a Great Web API - Evan Cooke - QCON 2011
Building a Great Web API - Evan Cooke - QCON 2011
Building a Great Web API - Evan Cooke - QCON 2011
Building a Great Web API - Evan Cooke - QCON 2011
Building a Great Web API - Evan Cooke - QCON 2011
Building a Great Web API - Evan Cooke - QCON 2011
Building a Great Web API - Evan Cooke - QCON 2011
Building a Great Web API - Evan Cooke - QCON 2011
Building a Great Web API - Evan Cooke - QCON 2011
Building a Great Web API - Evan Cooke - QCON 2011
Building a Great Web API - Evan Cooke - QCON 2011
Upcoming SlideShare
Loading in...5
×

Building a Great Web API - Evan Cooke - QCON 2011

2,178

Published on

This presentation explores how fast signup, a clear value proposition, efficient quick starts, concise documentation, easy authentication and debugability are common attributes of many successful web APIs. The Twilio API is used as an example of how a focus on developer experience helps drive API adoption.

Published in: Technology

Building a Great Web API - Evan Cooke - QCON 2011

  1. 1. BUILDING AGREAT WEB APINOVEMBER 17, 2011, QCON T PEVAN COOKE @emcooke H TCO-FOUNDER & CTO twilio CLOUD COMMUNICATIONS
  2. 2. One simple goalfor building great Web APIs...
  3. 3. 5Minutes
  4. 4. It should take no more than 5 minutes for adeveloper to perform a useful task using your API for the first time
  5. 5. What is a Web API?Definition for today:• HTTP/HTTPS endpoint• JSON/XML• Hosted API/Web service• Example: Amazon S3
  6. 6. 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 CodesDeveloper Phone Dynamically Buy Numbers Phone NumbersEnd User
  7. 7. Why 5 Minutes?• Clear value proposition• Fast signup• Simple API• Efficient quickstarts• Concise accessible docs• Easy authentication (basic vs. oauth)• Debuggable
  8. 8. API Adoption FunnelHear about API Good APIs Try it Promote Adoption (tell friends) Build it Production Use Buy it Traction
  9. 9. API Adoption FunnelHear about API Try it 5-Minute Goal Build it Production Use Buy it Traction
  10. 10. 5-minute APIs API Design
  11. 11. Co un te rE 5-minute APIs xa API Design m ple
  12. 12. 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)
  13. 13. 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
  14. 14. Media processing API1 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?
  15. 15. Media processing API2 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?
  16. 16. Media processing API3 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?
  17. 17. Media processing API4 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
  18. 18. Media processing API5 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
  19. 19. 5-minute APIs API Design
  20. 20. 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/Funds{‘value’: 1000, ‘token’: ‘TX123’}
  21. 21. Self-documentation• Sweat what and how you name. Naming is is the best documentation.• Example:GET /Users/ID123GET /Users/ID123/FriendsGET /Users/ID123/Photos
  22. 22. 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
  23. 23. 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
  24. 24. Statefulness• When possible, offload the work of keeping state/history because it’s hard!• ExamplesPOST /CallsGET /Calls/CA123GET /Calls/CA123/Recordings/RE123
  25. 25. Predictability• The API should do what users expect• Examples <Play>music.mp3</Play> <Play>music.aiff</Play>
  26. 26. Responsiveness• When a response is available immediately, use a synchronous response. Otherwise, consider an asynchronous webhook rather then polling• Examples:POST /Object/TransformsBody cbUrl=http://b.com/response
  27. 27. Key Ideas• Idempotency• Self-documentation• RESTfulness• Versioning• Statefulness• Predictability• Responsiveness
  28. 28. 5-minute APIs “Good”
  29. 29. 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 Bloch, Google
  30. 30. Human-centric
  31. 31. Saleforce auth Campaigns from Adword API
  32. 32. Dynamic phone numberprovisioning via Twilio API
  33. 33. SaleforceCRM data Saleforce app APIs GoogleMaps API Twilio Client API
  34. 34. Simplicity
  35. 35. DEPLOYINGYOUR WEBAPI T P H T twilio CLOUD COMMUNICATIONS
  36. 36. Infrastructure• 100’s of prod 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
  37. 37. Website Deployment Content Frequency(Risk) 4 buckets Website CodeLog Scale 1000x REST API Big DB 100x Schema 10x 1x CMS PHP/Ruby Python/Java SQL etc. etc.
  38. 38. Website DeploymentContent 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
  39. 39. Cluster automation via boxconfig
  40. 40. Cluster automation via boxconfig• 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
  41. 41. Cluster automation via boxconfig role role role Start Roles Fetch ProvisionS3 SVN/git Boxconfig Base (AMI) Vanilla Linux Host (cloud/colo)
  42. 42. twilio Evan Cooke @emcooke
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×