Within the API space Developer Experience (DX) matters more than ever. The best way to gauge an API’s usability is through actual implementation with an integration.

In a previous article Building a Better Voice Mail Using Twilio, we consumed the Twilio API to implement a voice mail project and to better understand how a developer interacts with their API. We managed to finish the project with little difficulty and also realized how little coding is actually involved in the whole process.

But how was the developer experience throughout this integration? How usable, intuitive, or easy was the integration process with Twilio? What are the takeaways for API providers looking to improve their developer portals?

Now in this article we will examine what Twilio is doing right as well as the areas we feel could use improvement. If you are an API provider, consider this case study a real world extension of our 5 core features to consider offering to developers. Let’s start by examining how an integration with Twilio is accomplished and what functionalities can be exposed.

Twilio is More Than a “Standard” Web API

Twilio offers a REST API and also TwiML, a higher level markup language that lets you program interactions with their service. Their REST API is more focused on accessing information on your account and initiating outbound activity, e.g., making phone calls and sending SMS. On the other hand, TwiML is completely focused on listening to actions triggered by inbound events like receiving a phone call.

Why did Twilio choose to use a proprietary language to handle all inbound activity hooks when they could offer the same functionality using webhooks? One of the reasons is probably related to their target audience. By offering an XML-based markup language, they can reach a larger number of developers who don’t necessarily want to implement a webhook receiving API. Also, by using TwiML you don’t need any specific Web server or technology. You simply have to make your XML file available online.

5 Minute Sign Up Process

Signing up with Twilio is relatively straightforward, but there are a few things that could be easily improved. The first thing you notice is that during signup they try to validate your phone number. They use their own technology to do that as they attempt to send you an SMS or even call your phone. While this makes sense to users who want to use their phone number as a caller ID, it’s not required for all other use cases.

After this initial verification process, Twilio offers you a free phone number so that you can test the service. This is actually a good move because you get to use the service immediately. The bad thing, at least during the implementation of our voice mail project, is that you can’t use this number to receive phone calls. It would be helpful in some cases to have a number that could, at least, receive phone calls from the onset.

Even without the ability to make and receive phone calls, Twilio is already offering much more than most APIs. In less than 5 minutes, we were able to establish a real phone number to use to send and receive SMS and test their API. Twilio’s fluid signup process should be seen by other API providers as a model for quick onboarding and initial consumer retention.

So, what is needed to actually handle those incoming messages and calls? Read on to understand what interacting with Twilio is like.

Relatively Simple Infrastructure

A big part of interacting with Twilio has to do with the ability to serve static or generated XML files. All their incoming events let you specify URLs that will be called whenever an event is triggered. As an example, whenever someone calls your Twilio number a call is made to what they call the Voice URL. A number of POST parameters are passed to that URL and Twilio expects to receive a TwiML response defining how the call will be handled.

This means that you need to be able to host those TwiML files somewhere. While in most situations these can be static files, there are cases where you’ll want to dynamically build the response based on one of the POST parameters. A good example is programming a reaction for when someone records a voice message. You’ll probably want to perform an action based on the caller phone number and also access the voice recording.

To host static files, you can use any cloud storage service that lets you host raw file contents. GitHub and Dropbox are good candidates because you can easily generate URLs for your stored files. To host dynamic scripts, you’ll need a Web server capable of receiving HTTP POST requests, parsing the incoming data and dynamically crafting an XML response. This can be easily achieved by using a popular programming language like PHP and hosting your code on a service like Heroku.

Testing and Reporting Features

Twilio offers a number of testing and reporting tools to make your life easier while implementing and debugging your integration. One of these tools, the App Monitor, lets you analyze errors in detail, including request information. You can easily review which requests are generating errors, inspect their payloads and even replay requests while debugging. This is really handy during the experimentation process, and a life-saver when something goes wrong later on.

They also offer a comprehensive reporting tool that lets you inspect different event related information:

• Calls: a complete call log that includes call direction (inbound or outbound), caller IDs, duration, and eventual voice recordings.
• Messages: a report of all sent and received SMS messages including their body and caller IDs.
• Recordings: all voice recordings ever made including their duration and easy access to the associated call.

Offering such a detailed reporting tool is very important because it creates a sense of accountability and lets you quickly analyze and debug any misbehaving implementation.

Is Twilio an Example API Provider to Follow?

With their developer-oriented tools and easy usability, Twilio is a great service for other API providers to model. It’s interesting to see the effort they’ve put into their reporting tools, which all offer a fine grained level of detail. Their signup process is also something to be followed even though it could be slightly improved by allowing a free phone number to receive calls.

After reading this article, you should have a clearer understanding of what works and what doesn’t when offering developer-oriented products like Twilio. Our main takeaways from using the Twilio API were:

1. They offer a straightforward signup process.
2. You’ll immediately have a sandbox to test your integration.
3. Their documentation is comprehensive and complete.
4. It’s easy to troubleshoot calls by accessing their reporting tools.
5. They engage with developers using different communication channels.

These are also the 5 points to pay attention to when releasing your API.

Have you been using Twilio lately? What do you think of their API? Leave a comment here or get in touch to discuss this more!