0
twilio       CLOUD COMMUNICATIONSBUILDING A GREAT API        DECEMBER 6, 2010, CLOUDSTOCK                          EVAN CO...
Why make Great APIs?  Hear about API                    Good APIs                     Promote                    Adoption ...
Today’s discussion focuseson APIs exposed by Internetservices, however, the ideaswe discuss can be applied in      many co...
Where Do APIs Come From?• APIs that have grown from products                     End Users                Facebook        ...
Where Do APIs Come From?• APIs that are the product               End Users               Developers                Cloud ...
Twilio     Web service APIs to automate Voice and SMS                  communications                                     ...
Outline1. Case Studies2. Design3. Presentation4. Development
Case Studies
What NOT to Do•   Media processing API Vendor•   Telecom API
Media processing API•   HTTP API to analyze large    media files•   Tx Rate 100,000/day    (costly)                        ...
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...
What NOT to Do•   Media processing API Vendor•   Telecom API
Telecom API•   API to manage phone numbers•   Documentation is 300 page PDF,    pages of WSDL•   95% useless RPC functions...
Design
Key Ideas•   Idempotency•   Self-documenting•   RESTfulness•   Versioning•   Statefulness•   Predictability•   Sync vs. As...
Idempotency• Idempotence is the property of certain  operations that they can be applied multiple  times without changing ...
Self-documenting• Sweat what and how you name. Naming is  is the best documentation.• Example:GET /Users/ID123GET /Users/I...
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/v1/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>
Sync vs Async• When a response is available immediately,  use a synchronous response. Otherwise,  consider an asynchronous...
Presentation
Great APIs•   Redis - Key/Value, List, and Set Persistence•   Dropbox - REST, iOS/Android File Mgnt•   Wufoo - Web forms  ...
Redis•   Simple, well    named API calls•   Powerful•   APIs that cover    major operational    tasks
Dropbox•   API support    across platforms/    languages•   Community    integration
Wufoo• Simple well-  documented  REST API• Good use of  HTTP verbs  and errors
What makes a Good API? • Easy to Learn • Easy to use (even without documentation) • Hard to Misuse • Easy to read and main...
Easy to Learn
Easy to Use
Easy to read/maintain code            HTTP/XML/JSON               REST         Customer  Telecom                   Busines...
Sufficiently            PowerfulIt sure helps to write code live if you are pitching todevelopers. John got a big nod from t...
Easy to extend            Expose Twilio         in an async evented                model
Development
Twilio Process1. Customers Feedback2. Documentation3. Team feedback (back to 2)4. Prototype (2-3 weeks)5. Alpha customers6...
Design  Idempotent, self-documenting, RESTful,  versioned, stateful, predictable, sync/asyncPresentation  Easy to learn, e...
Be Simple
twiliohttp://www.twilio.com      @emcooke
Upcoming SlideShare
Loading in...5
×

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

7,311

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

Transcript of "Building A Great API - Evan Cooke, Cloudstock, December 2010"

  1. 1. twilio CLOUD COMMUNICATIONSBUILDING A GREAT API DECEMBER 6, 2010, CLOUDSTOCK EVAN COOKE
  2. 2. Why make Great APIs? Hear about API Good APIs Promote Adoption Use in production (tell friends)
  3. 3. Today’s discussion focuseson APIs exposed by Internetservices, however, the ideaswe discuss can be applied in many contexts
  4. 4. Where Do APIs Come From?• APIs that have grown from products End Users Facebook API API API
  5. 5. Where Do APIs Come From?• APIs that are the product End Users Developers Cloud API
  6. 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. 7. Outline1. Case Studies2. Design3. Presentation4. Development
  8. 8. Case Studies
  9. 9. What NOT to Do• Media processing API Vendor• Telecom API
  10. 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. 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. 12. Media processing API1 Original Request POST http://api.vendor.com/API/Process? key=2hkh&mode=bob&filter=yeah Body is 100MB of binary data
  13. 13. 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
  14. 14. 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
  15. 15. 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
  16. 16. 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
  17. 17. What NOT to Do• Media processing API Vendor• Telecom API
  18. 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. 19. Design
  20. 20. Key Ideas• Idempotency• Self-documenting• RESTfulness• Versioning• Statefulness• Predictability• Sync vs. Async
  21. 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. 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. 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. 24. Versioning• Do it. Remember you will be stuck supporting old API versions (indefinitely?)• Examples GET /api/v1/blag GET /api/20101206/blag
  25. 25. Statefulness• When possible, offload the work of keeping state/history because it’s hard!• ExamplesPOST /CallsGET /Calls/CA123GET /Calls/CA123/Recordings/RE123
  26. 26. Predictability• The API should do what users expect• Examples <Play>music.mp3</Play> <Play>music.aiff</Play>
  27. 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=http://b.com/response
  28. 28. Presentation
  29. 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. 30. Redis• Simple, well named API calls• Powerful• APIs that cover major operational tasks
  31. 31. Dropbox• API support across platforms/ languages• Community integration
  32. 32. Wufoo• Simple well- documented REST API• Good use of HTTP verbs and errors
  33. 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. 34. Easy to Learn
  35. 35. Easy to Use
  36. 36. Easy to read/maintain code HTTP/XML/JSON REST Customer Telecom Business Goo Logic
  37. 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. 38. Easy to extend Expose Twilio in an async evented model
  39. 39. Development
  40. 40. Twilio Process1. Customers Feedback2. Documentation3. Team feedback (back to 2)4. Prototype (2-3 weeks)5. Alpha customers6. Preview Customers7. General Release
  41. 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. 42. Be Simple
  43. 43. twiliohttp://www.twilio.com @emcooke
  1. A particular slide catching your eye?

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

×