Building A Great API - Evan Cooke, Cloudstock, December 2010
-
Upload
twilio -
Category
Technology
-
view
8.380 -
download
1
description
Transcript of Building A Great API - Evan Cooke, Cloudstock, December 2010
twilioCLOUD COMMUNICATIONS
BUILDING A GREAT APIDECEMBER 6, 2010, CLOUDSTOCK
EVAN COOKE
Why make Great APIs?
Hear about API
Use in production(tell friends)
Good APIsPromoteAdoption
Today’s discussion focuses on APIs exposed by Internet services, however, the ideas we discuss can be applied in
many contexts
Where Do APIs Come From?
• APIs that have grown from products
End Users
API
API
API
Where Do APIs Come From?
• APIs that are the product
Developers
End Users
Cloud API
SMS Phone NumbersVoice
Twilio
Inbound CallsOutbound Calls
IVR
Web service APIs to automate Voice and SMS communications
To/From Phone Numbers
Short Codes
APIs to Dynamically
Provision Phone Numbers
1. Case Studies
2. Design
3. Presentation
4. Development
Outline
Case Studies
• Media processing API Vendor
• Telecom API
What NOT to Do
• HTTP API to analyze large media files
• Tx Rate 100,000/day (costly)
• POST data to the API
• API synchronously returns analysis of media (could be minutes/hours later)
Media processing API
You APIMedia
Analysis
• Control and data in the same request (100 MB every request)
• Unclear error conditions. Can you resend request?
• Synchronously wait for response
• No request history/billing information
Media processing API
You API???
Media processing API
POST http://api.vendor.com/API/Process?key=2hkh&mode=bob&filter=yeah
Body is 100MB of binary data
1 Original Request
Media processing API
POST http://api.vendor.com/API/Process?key=2hkh&mode=bob&filter=yeah&token=TK123
Body is 100MB of binary data
Add a token allowing us to safely retry2
Media processing API
POST http://api.vendor.com/API/Process?key=2hkh&mode=bob&filter=yeah&token=TK123&cbUrl=http%3A%2F%2Fmyserver.com%2Fresponse
Body is 100MB of binary data
Add webhook url to asynchronously respond3
Media processing API
POST http://api.vendor.com/API/ProcessBody
key=2hkhmode=bobfilter=yeahtoken=TK123cbUrl=http://myserver.com/responsemediaUrl=http://s3.com/media.mov
Async fetch media & move POST params to body4
Media processing API
POST http://api.vendor.com/v1/MediaBody
key=2hkhmode=bobfilter=yeahtoken=TK123cbUrl=http://myserver.com/responsemediaUrl=http://s3.com/media.mov
ResponseURI http://api.vendor.com/v1/Media/MD123
Version API and make URL more RESTful5
• Media processing API Vendor
• Telecom API
What NOT to Do
• 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
Telecom API
Design
• Idempotency
• Self-documenting
• RESTfulness
• Versioning
• Statefulness
• Predictability
• Sync vs. Async
Key Ideas
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
• Fetch
• Modify
• Remove
POST /Users
GET /Users/ID123
PUT/POST /Users/ID123
DELETE /Users/ID123
Versioning• Do it. Remember you will be stuck
supporting old API versions (indefinitely?)
• Examples
GET /api/v1/blagGET /api/20101206/blag
Statefulness• When possible, offload the work of keeping
state/history because it’s hard!
• Examples
POST /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
• Redis - Key/Value, List, and Set Persistence
• Dropbox - REST, iOS/Android File Mgnt
• Wufoo - Web forms
Great APIs
Other Notable APIsSimpleGeo, Github, Posterous, Tumblr,Facebook... great, but getting to their docs requires authenticating!
• Simple, well named API calls
• Powerful
• APIs that cover major operational tasks
Redis
• API support across platforms/languages
• Community integration
Dropbox
• Simple well-documented REST API
• Good use of HTTP verbs and errors
Wufoo
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 audienceHow to Design a Good API and Why it MattersJoshua Block, Google
Easy to Learn
Easy to Use
Easy to read/maintain code
HTTP/XML/JSON
REST
TelecomGoo
BusinessLogic
Customer
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.
Easy to extend
Expose Twilioin an async evented
model
Development
Twilio Process1. Customers Feedback
2. Documentation
3. Team feedback (back to 2)
4. Prototype (2-3 weeks)
5. Alpha customers
6. Preview Customers
7. General Release
Design Idempotent, self-documenting, RESTful, versioned, stateful, predictable, sync/async
PresentationEasy to learn, easy to use, easy to read and maintainable, sufficiently powerful, easy to extend
DevelopmentCustomers, documentation, team, prototype, alpha customers, preview customers, release
Be Simple
twiliohttp://www.twilio.com
@emcooke