'Designing the Best Telecom API on the Planet' - Tim Milliron

Transcript

1. twilio CLOUD COMMUNICATIONS Designing the Best Telecommunications API Tim Milliron, Director of Engineering @timmilliron
2. 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
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. /Calls?access_token=xxxyyyzzz /IncomingPhoneNumbers?access_token=xxxyyyzzz ... #5 The Smallest API Possible... twilio.com/ authorize access_token= xxxyyyzzz
11. /Calls /IncomingPhoneNumbers ... #5 The Smallest API Possible... twilio.com/ authorize account_sid= AC678
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 Spec Build Developers Developers Developers
15. twilio CLOUD COMMUNICATIONS Tim Milliron, Director of Engineering @timmilliron