• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
7 Principles of API Design - Waza

7 Principles of API Design - Waza



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

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



Total Views
Views on SlideShare
Embed Views



4 Embeds 100

http://wwwtst.atd.x.recruit.co.jp 50
http://lanyrd.com 41
http://mysoaone.blogspot.com.au 8
http://us-w1.rockmelt.com 1


Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
Post Comment
Edit your comment

    7 Principles of API Design - Waza 7 Principles of API Design - Waza Presentation Transcript

    • 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