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.

1. twilio
CLOUD COMMUNICATIONS
BUILDING A GREAT API
DECEMBER 6, 2010, CLOUDSTOCK
EVAN COOKE

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

3. Today’s discussion focuses
on APIs exposed by Internet
services, however, the ideas
we discuss can be applied in
many contexts

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

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

6. Twilio
Web service APIs to automate Voice and SMS
communications
Phone
Voice SMS
Numbers
Inbound Calls To/From Phone APIs to
Outbound Calls Numbers Dynamically
IVR Short Codes Provision Phone
Numbers

7. Outline
1. Case Studies
2. Design
3. Presentation
4. Development

8. Case Studies

9. What NOT to Do
• Media processing API Vendor
• Telecom API

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. 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. 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

13. 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

14. 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

15. 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

16. 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

17. What NOT to Do
• Media processing API Vendor
• Telecom API

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. Design

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

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. Self-documenting
• Sweat what and how you name. Naming is
is the best documentation.
• Example:
GET /Users/ID123
GET /Users/ID123/Friends
GET /Users/ID123/Photos

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. Versioning
• Do it. Remember you will be stuck
supporting old API versions (indefinitely?)
• Examples
GET /api/v1/blag
GET /api/20101206/blag

25. 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

26. Predictability
• The API should do what users expect
• Examples
<Play>music.mp3</Play>
<Play>music.aiff</Play>

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/Transforms
Body
cbUrl=http://b.com/response

28. Presentation

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. Redis
• Simple, well
named API calls
• Powerful
• APIs that cover
major operational
tasks

31. Dropbox
• API support
across platforms/
languages
• Community
integration

32. Wufoo
• Simple well-
documented
REST API
• Good use of
HTTP verbs
and errors

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. Easy to Learn

35. Easy to Use

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

37. 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.

38. Easy to extend
Expose Twilio
in an async evented
model

39. Development

40. Twilio Process
1. Customers Feedback
2. Documentation
3. Team feedback (back to 2)
4. Prototype (2-3 weeks)
5. Alpha customers
6. Preview Customers
7. General Release

41. Design
Idempotent, self-documenting, RESTful,
versioned, stateful, predictable, sync/async
Presentation
Easy to learn, easy to use, easy to read and
maintainable, sufficiently powerful, easy to extend
Development
Customers, documentation, team, prototype,
alpha customers, preview customers, release

42. Be Simple

43. twilio
http://www.twilio.com
@emcooke