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

Facebook

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