Tim Milliron's talk from Heroku's Waza event on "7 Principles of API Design at Twilio"

1. twilio
CLOUD COMMUNICATIONS
Designing the Best
Telecommunications API
Tim Milliron, Director of Engineering
@timmilliron

2. Who is twilio?
RESTful web APIs to automate
Voice & SMS communications
Voice SMS Phone
Numbers
• Inbound • Incoming • PhoneNumber
• Outbound • Outgoing Provisioning
• Mobile VoIP • Short Codes • ShortCode
• Browser VoIP Applications

3. (415) 233-WAZA
• Find & buy a number:
curl -u $U:$P
https://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>

4. 7 Principles

5. #1 APIs are for Abstraction
Example: DIDs
DID
(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 DIDs
twilio’s API talks PhoneNumbers
(they work for incoming & outgoing)

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

7. #3 Be RESTful
Hypermedia 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>

8. #3 Be RESTful
Hypermedia 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>

9. #4 The API Giveth...
... but the API can’t (usually) taketh away
It’s much easier to add something
than to remove something
➡ Get it in developers’ hands,
see what use cases develop.
➡ Then, aggressively add
frequently-requested features

10. #5 The Smallest API Possible...
twilio.com/
authorize
access_token=
xxxyyyzzz
/Calls?access_token=xxxyyyzzz
/IncomingPhoneNumbers?access_token=xxxyyyzzz
...

11. #5 The Smallest API Possible...
twilio.com/
authorize
account_sid=
AC678
/Calls
/IncomingPhoneNumbers
...

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

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

14. Process Perspective
Discuss Developers
Developers
Spec
Developers
Build

15. twilio
CLOUD COMMUNICATIONS
Tim Milliron, Director of Engineering
@timmilliron