7 Principles of API Design - Waza

4,080 views
3,725 views

Published on

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

Published in: Technology, Business
0 Comments
4 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
4,080
On SlideShare
0
From Embeds
0
Number of Embeds
121
Actions
Shares
0
Downloads
85
Comments
0
Likes
4
Embeds 0
No embeds

No notes for slide

7 Principles of API Design - Waza

  1. twilio CLOUD COMMUNICATIONS Designing the BestTelecommunications 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:$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>
  4. 7 Principles
  5. #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)
  6. #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
  7. #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>
  8. #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>
  9. #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
  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 COMMUNICATIONSTim Milliron, Director of Engineering @timmilliron

×