Many paths are available to a APIs supplier-minded organization seeking to engage its 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 can learn all that is possible about the API(s). There are a number of facets that go into the major API portals and ProgrammableWeb has created a series of articles that help you understand the best practices used by real-world API providers.
ProgrammableWeb kicked off this series with a comprehensive checklist of the criteria needed to create a world-class API development portal. The following Editor’s Choice articles, including this one, will provide a more in-depth look at how individual vendors performed on the various criteria. In some of these cases, we review the entire portal while in others, we award an Editor’s Choice award for outstanding execution on specific criteria elements.
One way for an API provider to support their users is to provide a downloadable API description for each of their APIs. There are a number of options available when it comes to description formats such as OAS (most popular for RESTful APIs), Postman Collections (executable API descriptions), AsyncAPI (for event driven APIs), RAML and Blueprint. The choice may depend on factors such as the type of API you offer and the format that best suits your users, but the important thing is that you make the descriptions available.
Earlier this year, Twilio announced that it had opened an OpenAPI specification in beta for each Twilio API. In total, Twilio has made description files available for 33 APIs, in both JSON and the YAML format. A private pilot for this feature ran from November through April 2021. When asked if the OAS files would be pushed to general availability, a Twilio representative said the company was “seeking feedback from a more large number of clients. Additionally, there have been some interesting changes in the OpenAPI specification from 3.0.1 to 3.1.0 that we are working on, particularly around Version management.”
Below is an excerpt from the Programmable Voice API YAML file 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: Excerpt from OAS YAML file for ProgrammableVoice API
This snippet shows that the description file includes the path to the BulkCountryUpdate resource, the action that can be taken on the resource (POST in this case), 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 embed them in the API Reference. Twilio currently does not, instead linking to OAS files in its SDK section.
Figure 2: Twilio is currently linked to its OAS files under the SDKs menu and can optionally link them directly into the API reference.
We asked Twilio if they plan to link the OAS files directly in the API reference and a spokesperson replied: “in the short term we will not be linking to the OAS files, we may possibly linking in the future. We’re learning all the ways Twilio customers are using OpenAPI, which will guide our decision on docs.”
There are a number of benefits to providing an API description; it allows you to describe your API in detail while making it consumable by the machine, its standardized format means you can automate processes such as auto-generation Documentation and code creation for server implementations, and it allows you to submit your API to directories and marketplaces, making it more discoverable. Twilio touts the ability for developers to generate new client libraries and test its APIs as immediate benefits of offering OpenAPI specifications.
By creating OAS files for its entire suite of APIs, Twilio has taken steps to make them more easily consumable and discoverable. For this reason, Twilio won the ProgrammableWeb Editor’s Choice award for Developer Experience.
