Introducing Twilio’s OpenAPI Specification GA

March 08, 2023
Written by

open-api-ga

Today, we are thrilled to share the news that we have officially open-sourced the OpenAPI specification for every Twilio API.

As a commitment to supporting and streamlining the development process for our users, we have long provided helper libraries and tooling in various popular programming languages and environments. With this announcement, we are taking it one step further by offering Twilio API documentation in compliance with the widely adopted OpenAPI Specification. This empowers developers to effortlessly integrate Twilio into their projects, regardless of their preferred language or tools.

What can you do with OpenAPI?

Client Library Generation

Using the power of the Twilio OpenAPI specification and open-sourced OpenAPI generator, you can now generate new client libraries. This makes it much more convenient to use Twilio in your preferred programming language, without writing complex methods and functions. As an example, it is now possible to programmatically build a strongly-typed Rust library for Twilio’s API methods.

use dotenv;

use std::env;

use openapi::apis::{configuration::Configuration, default_api as twilio_api};

#[tokio::main]

async fn main() {

dotenv::dotenv().expect("Failed to read .env file");

let account_sid = env::var("TWILIO_ACCOUNT_SID").expect("Failed to parse Account SID");

let api_key = env::var("TWILIO_API_KEY").expect("Failed to parse API Key");

let api_key_secret = env::var("TWILIO_API_KEY_SECRET").expect("Failed to parse API Key Secret");

let mut twilio_config = Configuration::default();

// Supply Basic Auth credentials.

twilio_config.basic_auth = Some((api_key, Some(api_key_secret)));

let balance = twilio_api::fetch_balance(&twilio_config, &account_sid)

.await

.unwrap();

println!("{:?}", balance);

}

To learn more about helper library generation see our OpenAPI Generator Project on GitHub or Twilio docs on helper library generation.

Mock Testing

Using the OpenAPI Specification, you can now mock Twilio’s API to emulate real API calls locally, which makes test suite integration with Twilio faster and less brittle.

For example, you can now easily make a mock server of Twilio’s API portable with Docker.

# Dockerfile
# Choose the base image for us to build from.
FROM alpine

# Install dependencies.
RUN apk update && \
 apk add --update git && \
 apk add --update npm && \
 npm i -g @stoplight/prism-cli

# Clone the Twilio OpenAPI spec.
RUN git clone https://github.com/twilio/twilio-oai.git

# Perform preprocessing on the v2010 spec JSON file.
RUN sed -i.bak '/pattern:/d' ./twilio-oai/spec/json/twilio_api_v2010.json && \
 sed -i.bak 's/</Before/' ./twilio-oai/spec/json/twilio_api_v2010.json && \
 sed -i.bak 's/>/After/' ./twilio-oai/spec/json/twilio_api_v2010.json

# Expose the port that Prism runs on.
EXPOSE 4010

# Run Prism!
CMD ["prism", "mock", "-h", "0.0.0.0", "./twilio-oai/spec/json/twilio_api_v2010.json"]

To learn more about mock testing, see our docs.

Postman Support

We have also added support for Postman, which is a free, straightforward development tool for making API calls with a variety of helpful features. Instead of referencing the Twilio Docs and creating your own collection, you can visit the Twilio Postman Collection page where you will find collections maintained by the Twilio team. You can also browse the Twilio Postman APIs visually using Postman.

Head over to our docs to read more about using Twilio's Postman Collections.

Try it Out!

We can’t wait to see all the amazing things you’ll build with Twilio’s OpenAPI Specification! 🚀

If you have any questions or feedback, please do not hesitate to reach out at gjones[at]twilio.com. We look forward to hearing from you!