Understanding the API Conventions

In designing the API for TwilioClient, we tried to keep four things in mind:
  • Simplicity - You shouldn't have to be a Twilio Expert to get started
  • Consistency - Conventions should be the same across the board
  • Discoverability - Intuitive design, coupled with IntelliSense should make it easy to build out large voice applications quickly
  • Upgradability - Make it easy to get off of Twilio's C# library, and also make the system adaptable to future API changes

Object Design

The objects were designed directly from the Twilio API Reference, and much of the IntelliSense documentation was taken directly from Twilio's reference material. In designing the objects, a deliberate decision was made to only include properties that were being returned by Twilio, and to not represent caller-to-Twilio-only arguments as properties. There are two reasons for this:
  1. Because the XmlSerializer replaces the object submitted to Twilio with the the object Twilio returns in it's response, so one-way properties would not be visible on the return anyway,
  2. Because Twilio's official C# library works in a similar (but slightly more rudimentary) manner... making existing code more easily upgradable.
Note: I'd be interested in a discussion on this topic if this is contrary to expected behavior. It can be changed relatively easily without breaking code built with the first release.

The TwilioClient documentation is currenly being updated to more clearly illustrate where PostArguments are required, and where they are optional. For the time being, the sample TwilioConsole outlines the use for nearly every method call in the API, and is a great starting point.

Manager Method Calls

There are 4 different method calls that you will see consistently in every manager:
  • GetAll()
  • Get(instanceSid);
  • Add
  • Update
There are two exceptions to this rule:
  • The IncomingPhoneNumberManager uses AddLocal(); and AddTollFree(); methods (these were a holdover from an earlier design that tried to avoid non-WCF code, and will likely change in V1.)
  • The CallManager uses PlaceCall() instead of Add(). PlaceCall() felt more intuitive, as it more accurately described what was happening on the back-end.

Last edited Jun 22, 2009 at 3:03 AM by interscape, version 1

Comments

No comments yet.