7 Principles of API Design - Waza
4 likes2,624 views
Twilio is a cloud communications platform that provides RESTful APIs for voice, SMS, and phone number management. The document discusses 7 principles for API design based on Twilio's experience: (1) APIs abstract complexity, (2) resources are nouns not verbs, (3) APIs should be RESTful, (4) APIs should make it easy to add features but not remove them, (5) APIs should be as small as possible but no smaller, (6) common cases should be easy but flexibility allowed, and (7) get feedback throughout development and be open to changes.
7 Principles of API Design - Waza
- 1. twilio CLOUD COMMUNICATIONS Designing the Best Telecommunications 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:$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>[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>
- 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. #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 COMMUNICATIONS Tim Milliron, Director of Engineering @timmilliron