Declarative APIs

May 24, 2017
Written by


When Twilio started, our mission was to bring the flexibility of software to the stodgy and inflexible world of communication. Our APIs enabled developers to make phone calls and to send text messages in a way they never could before.

As developers brought innovative Twilio-powered applications to market, we started to see patterns — places developers got stuck and common challenges they were having. So we started building tools like Copilot to effectively deliver messages, and Insights to understand how your phone calls perform in real-time.

And as developers brought even MORE innovative applications to market, we again saw developers repeating design application patterns and boilerplate functionality that was important for their application, but not core to their business. Problems such as two factor authentication or managing a customer’s communication preferences.

For many of these problems, we found ourselves asking “Why isn’t that an API?”. So we began wrapping up the most common design patterns into self-contained APIs that solve a specific business problem. These newer APIs look somewhat different from our earlier APIs. Of course, they’re still REST and still well documented. But with these newer APIs, developers no longer tell Twilio to execute an action, but rather to achieve an outcome.

Consider Notify, a cross channel, user-centric API for sending out notifications across Push, SMS, and Facebook Messenger. Historically, to send mass-notifications across multiple channels, developers wrote for-loops and conditionals. Today, a developer can make a single API call to Notify and Twilio figures out how to message each person via the right channel at the that time.

# With Notify, you tell us the segment of users to communicate with. 
# Twilio figures out HOW to do it

notification = service.notifications.create(
  body: 'Hello, New Users!',
  segment: 'new_users'

And if you’re using Task Router, you tell Twilio that you want to connect a caller to an agent, and Task Router does the heavy lifting of matching the caller with the best available agent. Maybe the caller speaks Spanish, or the agent needs to work in Sales. But you no longer need to concern yourself with writing efficient matching algorithms.
Or consider Authy’s API for two factor authentication. We watched countless developers reinvent two factor authentication, each repeating the same design patterns: generating PINs, sending messages, and authorizing users. But with Authy, developers simply tell Twilio what outcome they want to achieve: the authentication of a user. Twilio then takes care of the implementation, whether the PIN is delivered via SMS, One Touch, or a one time password.

There’s a word for this pattern in computer science: declarative programming. In declarative programming, developers tell an application what they are trying to achieve. Contrast this to imperative programming, where a developer specifies exactly how to do it.

At Twilio we call our new generation of Twilio products “Declarative APIs”. These new APIs encapsulate common design patterns and best practices. Developers tell these APIs what they want to do, not how to do it. Twilio is responsible for the heavy lifting, for writing the efficient algorithms, and for employing the best security practices. Declarative APIs free developers from reinventing the wheel so that they can focus on creative problems and competitive differentiation.
Our newest product, Proxy, is a fantastic example of a declarative API. Privately connecting two parties across your mobile workers and/or customers is an incredibly common design pattern. Riders and drivers. Guests and hosts. Teachers and students. Buyers and sellers.

But managing pools of numbers is complicated, and standing up servers just to proxy messages and phone calls back and forth is a tax on creativity. Scale across multiple countries or across multiple communication channels like Chat and Facebook, and suddenly companies need full time developers just to manage the plumbing required for proxied communications.

With Proxy, you just tell Twilio to connect two people, and we take care of the rest:

#Create a conversation session with our reservation id

reservation = service.sessions.create(
 unique_name: "reservation_12345"

host = session.participants.create(identifier: "+12345678901")
guest = session.participants.create(identifier: "+12345678902")

#That's it! The guest and host can now privately communicate

We can’t wait to see what you declare.