7 Principles of API Design - Waza

twilio CLOUD COMMUNICATIONS Designing the BestTelecommunications API Tim Milliron, Director of Engineering @timmilliron

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

(415) 233-WAZA • Find & buy a number:curl -u $U:$Phttps://api.twilio.com/2010-04-01/Accounts/AC123/AvailablePhoneNumbers/US/Local?Contains=415***WAZAcurl -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 AbstractionExample: 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/.../CallsNot 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.coms 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 awayIt’s much easier to add somethingthan to remove something ➡ Get it in developers’ hands, see what use cases develop. ➡ Then, aggressively add frequently-requested features

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

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

#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 Perspective Discuss Developers Developers Spec Developers Build

twilio CLOUD COMMUNICATIONSTim Milliron, Director of Engineering @timmilliron

http://wwwtst.atd.x.recruit.co.jp	50
http://lanyrd.com	40
http://us-w1.rockmelt.com	1

7 Principles of API Design - Waza

by Twilio

Accessibility

Categories

Upload Details

Usage Rights

3 Embeds 91

Statistics

7 Principles of API Design - Waza Presentation Transcript