Introducing Twilio’s Next Generation Helper Libraries

February 08, 2016
Written by
Billy Chia


At Twilio, 77% of all requests to our REST API are made by a helper library user-agent. It’s the most common touch point between Twilio and you, the developer.

That’s why we’re so excited to announce early access to the next generation of our Python and Ruby helper libraries. These next-gen libraries are built on a new API auto-generation tool, homegrown within Twilio, designed to make all future helper libraries a whole lot better.

As Twilio has grown, introducing new products like Video, IP Messaging and SIP Trunking, our API surface has grown as well. Twilio’s first helper libraries were written in only a few languages, and supported only 12 endpoints. We now support 8 subdomains and over 200 endpoints in 7 languages: C#, Java, Python, PHP, Ruby, Node.js and Salesforce. Manually generating all of these libraries at the level of excellence developers have come to expect from us has become a daunting challenge.

We found that the best way to address this challenge was to introduce a healthy dose of automation into the process. We were inspired by projects like boto3, raml-codegen and swagger, which auto-generate API code and documentation. All of these projects have shown that generating helper libraries off of declarative definitions can be effective and maintainable.

Following their lead, our in-house solution allows us to almost completely auto-generate our helper libraries. We’ve kept in a few layers of manual configuration and optimization. This approach allows us to continually improve our helper libraries at scale while maintaining the human-friendly, “hand-crafted” feel that developers come to know and love as a distinctive mark of Twilio’s helper libraries.

Advantages Of Automation

In a nutshell, automating our library generation allows us to improve the developer experience and increase the pace at which we iterate. It means we can bring you new features and languages much faster than when all of our helper libraries were manually generated. Additionally, we’ve taken the opportunity of re-architecting our libraries to make several enhancements including:

  •   Optimized network efficiency (Make fewest number of REST calls necessary)
  •   Configurable page sizes for memory efficiency on constrained devices
  •   More consistent feature coverage across different languages
  •   Language idiomatic ways of expressing constructs (So C# feels like C#)
  •   Streaming Auto-Paging (my personal favorite new feature)
  •   Proper type serialization/de-serialization
  •   BYOHC (Bring Your Own HTTP Client)

With every engineering decision there are always tradeoffs. In order to gain these advantages we’ve had to trade backwards compatibility and simplicity in our community contribution model. Today, with this early release, we’re simply providing a summary of what to expect when our new auto-generated libraries become official later this year. Over the coming weeks you can expect more detailed blogs posts on specific features and how to contribute updates to the new auto-generated libraries. We’ll also soon be publishing release candidates for Node.js and PHP, followed by C# and Java.

We Need You

To get started visit the installation and migration guides linked below. We’d love to hear your thoughts on the release candidates of our Python and Ruby libraries. You can get support and provide feedback by opening an issue on Github and tagging the issue with “release-candidate”. Our engineering team monitors the issue and is looking forward to hearing from you.