Share
Embed
Transcript
15 slides
-
twilio CLOUD 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 automate Voice & SMS communications • Incoming • Outgoing • Short Codes • PhoneNumber Provisioning • ShortCode Applications -
(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> -
#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) -
#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 RESTful Hypermedia for sub-resource traversal: <Account> <Sid>AC123</Sid> <OwnerAccountSid>AC456</OwnerAccountSid>
<FriendlyName>[email protected]'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 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> -
#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 -
#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