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

twilio CLOUD COMMUNICATIONSBUILDING A GREAT API DECEMBER 6, 2010, CLOUDSTOCK EVAN COOKE

Why make Great APIs? Hear about API Good APIs Promote Adoption Use in production (tell friends)

Today’s discussion focuseson APIs exposed by Internetservices, however, the ideaswe discuss can be applied in many contexts

Where Do APIs Come From?• APIs that have grown from products End Users Facebook API API API

Where Do APIs Come From?• APIs that are the product End Users Developers Cloud API

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

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 ﬁles• 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)

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

Media processing API1 Original Request POST http://api.vendor.com/API/Process? key=2hkh&mode=bob&filter=yeah Body is 100MB of binary data

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

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

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

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

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 that expose internal business logic• No simple way to get started• No helper libraries

Design

Key Ideas• Idempotency• Self-documenting• RESTfulness• Versioning• Statefulness• Predictability• Sync vs. Async

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’}

Self-documenting• Sweat what and how you name. Naming is is the best documentation.• Example:GET /Users/ID123GET /Users/ID123/FriendsGET /Users/ID123/Photos

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

Versioning• Do it. Remember you will be stuck supporting old API versions (indeﬁnitely?)• Examples GET /api/v1/blag GET /api/20101206/blag

Statefulness• When possible, ofﬂoad the work of keeping state/history because it’s hard!• ExamplesPOST /CallsGET /Calls/CA123GET /Calls/CA123/Recordings/RE123

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 Webhook rather then polling• Examples:POST /Object/TransformsBody cbUrl=http://b.com/response

Presentation

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!

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 maintain code that uses it • Sufﬁciently powerful to satisfy requirements • Easy to extend • Appropriate to audience How to Design a Good API and Why it Matters Joshua Block, Google

Easy to Learn

Easy to Use

Easy to read/maintain code HTTP/XML/JSON REST Customer Telecom Business Goo Logic

Suﬃciently 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.

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. Preview Customers7. General Release

Design Idempotent, self-documenting, RESTful, versioned, stateful, predictable, sync/asyncPresentation Easy to learn, easy to use, easy to read and maintainable, suﬃciently powerful, easy to extendDevelopment Customers, documentation, team, prototype, alpha customers, preview customers, release

Be Simple

twiliohttp://www.twilio.com @emcooke

http://blog.programmableweb.com	395
http://www.techgig.com	51
http://flaviocopes.tumblr.com	20
http://lanyrd.com	12
http://static.slidesharecdn.com	9
https://demo.buddycloud.org	4
http://rss2.com	2
http://twitter.com	2
http://feeds2.feedburner.com	1
http://www.techgig.timesjobs.com	1
http://flaviocopes.com	1
http://www.govloop.com	1
http://blog.joocode.com	1
http://205.164.56.138	1
https://twimg0-a.akamaihd.net	1
http://www.cs.nott.ac.uk	1
http://paper.li	1
http://www.netvibes.com	1
http://localhost	1

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

by Twilio

Accessibility

Categories

Upload Details

Usage Rights

19 Embeds 506

Statistics