Twilio's Downloadable OAS Files Earn it an Editor's Choice Award

There are many avenues available to an API provider-minded organization looking to engage it’s ecosystem. Of these, one of the most critical steps is setting up and maintaining an API Developer Portal. A portal’s ability to showcase and explain an API can make or break its success and the portal is where current and future stakeholders will be able to learn everything possible about the API(s). A number of facets go into the leading API portals and ProgrammableWeb has created a series of articles that help you understand what best practices are being used by real-world API providers.

ProgrammableWeb kicked off this series with a comprehensive checklist of the criteria needed to build a world-class API developer portal. Subsequent Editor’s Choice articles including this one will provide a more in-depth look at how individual providers have executed on the various criteria. In some of these cases, we are looking at the overall portal while in others, we’re giving an Editor’s Choice award for exceptional execution on specific criteria items.

One way for an API provider to support its users is to provide a downloadable API description for each of its APIs. There are a number of available options when it comes to description formats such as OAS (most popular for RESTful APIs), Postman Collections (executable API descriptions), AsyncAPI (for evented APIs), RAML and Blueprint. The choice can depend on factors such as the type of API you are offering and what format best serves your users, but the important thing is that you make the descriptions available.

Earlier this year Twilio announced that it open-sourced an OpenAPI specification in Beta for every Twilio API. In total Twilio has made description files available for 33 APIs, in both JSON and YAML format. A private pilot for this feature was run from November through April 2021. When asked if the OAS files would be pushed to general availability, a Twilio rep said that the company is "looking for feedback from more customers. Additionally, there were some interesting changes in OpenAPI spec from 3.0.1 to 3.1.0 that we are working through, especially around Versioning."

Below is a snippet of the YAML file of the Programmable Voice API showing the DialingPermissions BulkCountryUpdate Resource.

/v1/DialingPermissions/BulkCountryUpdates:
    description: 'TODO: Resource-level docs'
post:
      description: Create a bulk update request to change voice 
dialing country permissions
        of one or more countries identified by the corresponding [ISO 
country code]( HTTPS://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
      operationId: CreateDialingPermissionsCountryBulkUpdate
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                UpdateRequest:
                  description: ' URL encoded JSON array of update objects. example
                   : `[ { "iso_code": "GB", "low_risk_numbers_enabled": 
  "true", "high_risk_special_numbers_enabled":"true",
                    "high_risk_tollfraud_numbers_enabled": "false" } ]`'
                  type: string
              required:
              - UpdateRequest
              title: CreateDialingPermissionsCountryBulkUpdateRequest
              type: object
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: 
'#/components/schemas/voice.v1.dialing_permissions.dialing_permissions_country_bulk_update'
          description: Created
      security:
      - accountSid_authToken: []
      x-maturity:
      - Preview
    servers:
    - url: https://voice.twilio.com
    x-default-output-properties:
    - update_request
    - update_count
    x-path-type: list

Figure 1: Snippet of the YAML OAS file for the ProgrammableVoice API

This snippet shows that the description file includes the path for the BulkCountryUpdate resource, the action that can be taken on the resource (POST in this instance), and what can be expected in the request and response bodies.

As mentioned in the API portal checklist article, the ideal way to access description files is to have them embedded in the API Reference. Twilio isn't currently doing this, instead of linking to the OAS files under its SDKs section.

Figure 2: Twilio currently links to its OAS files under the SDK menu and may eventually link them directly within the API reference.

Figure 2: Twilio currently links to its OAS files under the SDK menu and may eventually link them directly within the API reference.

We asked Twilio if they had plans to link the OAS files directly within the API reference and a spokesperson replied, "near-term we won't be linking to the OAS files, we may eventually link to them in the future. We're still learning all of the ways Twilio customers are using OpenAPI, which will guide our decision on docs."

There are a number of benefits for offering an API description; it allows you to describe your API in detail while also making it machine-consumable, its standardized format means that you can automate processes such as auto-generating Documentation and creating code for server implementations, and it allows you to submit your API to directories and marketplaces making it more discoverable. Twilio is touting the ability for developers to generate new client libraries and mock test its APIs as immediate benefits of offering the OpenAPI specs.

By creating OAS files for its entire suite of APIs, Twilio has taken steps towards making them more easily consumable and discoverable. For this reason, Twilio has earned a ProgrammableWeb Editor's Choice award for Developer experience.