twilioCLOUD COMMUNICATIONS

Designing the Best Telecommunications API

Tim Milliron, Director of Engineering@timmilliron

SMS Phone Numbers

Voice

Who is twilio?

• Inbound• Outbound• Mobile VoIP• Browser VoIP

RESTful web APIs to automateVoice & SMS communications

• Incoming• Outgoing• Short Codes

• PhoneNumber Provisioning

• ShortCode Applications

(415) 233-WAZA• Find & buy a number:

curl -u $U:$Phttps://api.twilio.com/2010-04-01/Accounts/AC123/AvailablePhoneNumbers/US/Local?Contains=415***WAZA

curl -u $U:$P -d “PhoneNumber=415233WAZA”https://api.twilio.com/2010-04-01/Accounts/AC123/IncomingPhoneNumbers/

• Make an outgoing call:curl -u $U:$P -d “Url=www.example.com/outgoing.xml”-d “From=4152339292” -d “To=4158675309”https://api.twilio.com/2010-04-01/Accounts/AC123/Calls/

• Receive an incoming call:<Response> <Say>Thanks for calling the Waza Twilio number! Huzzah!</Say> <Sms>Heroku’s Waza Rocks!</Sms></Response>

7 Principles

#1 APIs are for Abstraction

Example: DIDsDID  (Direct  Inward  Dial)  —  Inbound-­‐only  phone  number  assigned  to  a  group  of  phone  lines  that  allows  a  phone  system  to  route  to  a  unique  location  or  person.  A  group  of  DIDs  is  often  assigned  to  a  single  trunk  group.  DID  numbers  are  not  sent  out  as  the  ANI  when  the  caller  places  an  outbound  call.

Developers don’t give a f*** about DIDstwilio’s API talks PhoneNumbers(they work for incoming & outgoing)

#2 What’s the noun?Speak resources:

GET api.twilio.com/.../Calls

GET api.twilio.com/.../Calls/CA123

POST api.twilio.com/.../Calls

Not RPC:

GET api.twilio.com/.../GetCalls/

POST api.twilio.com/.../PlaceCall

#3 Be RESTfulHypermedia for sub-resource traversal:

<Account><Sid>AC123</Sid><OwnerAccountSid>AC456</OwnerAccountSid><FriendlyName>tim@twilio.com's Account</FriendlyName><Status>active</Status>...<Uri>

/2010-04-01/Accounts/AC123</Uri><SubresourceUris>

<AvailablePhoneNumbers>/2010-04-01/Accounts/AC123/AvailablePhoneNumbers

</AvailablePhoneNumbers><Calls>

/2010-04-01/Accounts/AC123/Calls</Calls>...

</SubresourceUris></Account>

#3 Be RESTfulHypermedia for list traversal:

<SMSMessages page="0" numpages="16" pagesize="50" total="780" start="0" end="49" uri="/2010-04-01/Accounts/AC123/SMS/Messages" firstpageuri="/2010-04-01/Accounts/AC123/SMS/Messages?Page=0&PageSize=50" previouspageuri="" nextpageuri="/2010-04-01/Accounts/AC123/SMS/Messages?Page=1&PageSize=50" lastpageuri="/2010-04-01/Accounts/AC123/SMS/Messages?Page=15&PageSize=50">

...</SMSMessages>

#4 The API Giveth...... but the API can’t (usually) taketh away

It’s much easier to add somethingthan to remove something

➡ Get it in developers’ hands,see what use cases develop.

➡ Then, aggressively addfrequently-requested features

/Calls?access_token=xxxyyyzzz/IncomingPhoneNumbers?access_token=xxxyyyzzz...

#5 The Smallest API Possible...

twilio.com/authorize

access_token=xxxyyyzzz

/Calls/IncomingPhoneNumbers...

#5 The Smallest API Possible...

twilio.com/authorize

account_sid=AC678

#6 ...But No Smaller“As close to C as possible, but no closer” - Bjarne Stroustrup, creator of C++

Make the common case easy.

This works, and it’s generic:curl api.twilio.com/.../AvailablePhoneNumbers?Contains=510*******

But, this is what most developers want:curl api.twilio.com/.../AvailablePhoneNumbers?AreaCode=510

#7 Don’t Settle

• Late changes are OK

• Don’t be afraid to version(with good reason)

• Get feedback early, often, & throughout

Discuss, spec, write, try it, rewrite discuss it some more, rewrite again

Process PerspectiveDiscuss

Spec

Build

Developers

Developers

Developers

twilioCLOUD COMMUNICATIONS

Tim Milliron, Director of Engineering@timmilliron