Twilio Makes for a Nice and Clean Example of APIs.json

You really can’t find a better example of APIs.json, then the one for Twilio. Twilio doesn’t have their own official APIs.json (yet), but I created one that I think really shows the strength of the API discovery format. I still have more work to do, but this Twilio APIs.json shows how the format can be used to index an API operation, while revealing individual human and machine readable properties of multiple APIs, as well as a common set of properties across all APIs–this version of my APIs.json for Twilio covers six of their APIs:

Video
Messaging
Email
Accounts
Programmable Voice
Identity and Verification

What I like is that each individual API has a property for human-readable documentation, as well as a property for the machine-readable OpenAPI, and the essential building blocks of an public API are defined as common properties shared by all APIs.

Sign-Up
About
Support
SDKs
Status
Change Log
Blog
Privacy
Terms of Service

Twilio still has other building blocks I want to index as part of this APIs.json, but I wanted to start somewhere. Ideally Twilio would manage their own index, but create one provides me with a good opportunity for pushing the APIs.json spec forward while also learning about how Twilio does what they do–here is the YAML edition of the APIs.json format I have right now.

name: Twilio
description: "We are a software company that strengthens businesses by unifying their
  data to build insightful paths to customers, so they are smarter with every interaction
  and able to outmaneuver their competition."
image: https://kinlane-productions2.s3.amazonaws.com/apis-json/apis-json-logo.jpg
url: https://www.twilio.com/en-us

created: 2023/9/25
modified: 2023/9/26
specificationVersion: '0.16'

tags:

  - SMS
  - Voice
  - Messaging
  - Identity
  - Verification

apis:

- name: Twilio Messaging API
  description: Send and receive messages via SMS, MMS, WhatsApp, Facebook Messenger,
    and more through our Messaging and Conversations APIs.
  image: https://kinlane-productions2.s3.amazonaws.com/apis-json/apis-json-logo.jpg
  humanURL: https://www.twilio.com/en-us/ahoy
  baseURL: https:/api.twilio.com
  tags:
    - Messaging
  properties:
    - type: X-documentation
      url: https://www.twilio.com/en-us/messaging
    - type: X-pricing
      url: https://www.twilio.com/en-us/sms/pricing/us 
    - type: X-openapi
      url: https://raw.githubusercontent.com/twilio/twilio-oai/main/spec/yaml/twilio_messaging_v1.yaml

- name: Twilio Email API
  description: Reach customers with the Twilio SendGrid Email API for reliable email
    delivery at scale.
  image: https://kinlane-productions2.s3.amazonaws.com/apis-json/apis-json-logo.jpg
  humanURL: https://www.twilio.com/en-us/sendgrid/email-api
  baseURL: https:/api.twilio.com
  tags:
   - Email
  properties:
    - type: X-documentation
      url: https://www.twilio.com/en-us/sendgrid/email-api
    - type: X-openapi
      url: ''

- name: Twilio Identity and Verification API
  description: Set up SMS or voice verifications to quickly authenticate users, fight
    fraud, and protect user accounts.
  image: https://kinlane-productions2.s3.amazonaws.com/apis-json/apis-json-logo.jpg
  humanURL: https://www.twilio.com/en-us/trusted-activation/verify
  baseURL: https:/api.twilio.com
  tags:
    - Verification
    - Identity
  properties:
    - type: X-documentation
      url: https://www.twilio.com/en-us/trusted-activation/verify
    - type: X-pricing
      url: https://www.twilio.com/en-us/verify/pricing 
    - type: X-openapi
      url: http://example.com/openapi.json

- name: Twilio Programmable Voice API
  description: Build custom voice call experiences for your applications to reach
    customers around the world.
  image: https://kinlane-productions2.s3.amazonaws.com/apis-json/apis-json-logo.jpg
  humanURL: https://www.twilio.com/en-us/voice
  baseURL: https:/api.twilio.com
  tags:
    - Voice
  properties:
    - type: X-documentation
      url: https://www.twilio.com/en-us/voice
    - type: X-openapi
      url: https://raw.githubusercontent.com/twilio/twilio-oai/main/spec/yaml/twilio_voice_v1.yaml

- name: Twilio Video API
  description: Twilio Video is a programmable real-time communications platform that allows you to add video chat functionality to your web, iOS, and Android applications. The platform provides APIs, SDKs, and helper tools to capture, distribute, record, and render high quality audio and video applications.
  image: https://kinlane-productions2.s3.amazonaws.com/apis-json/apis-json-logo.jpg
  humanURL: https://www.twilio.com/docs/video
  baseURL: https:/api.twilio.com
  tags:
    - Video
  properties:
    - type: X-documentation
      url: https://www.twilio.com/docs/video
    - type: X-openapi
      url: https://raw.githubusercontent.com/twilio/twilio-oai/main/spec/yaml/twilio_video_v1.yaml

- name: Twilio Accounts API
  description: When you first sign up with Twilio, you have just one account, your main account. But you can also create more accounts... subaccounts are useful for things like segmenting phone numbers and usage data for your customers and controlling access to data.
  image: https://kinlane-productions2.s3.amazonaws.com/apis-json/apis-json-logo.jpg
  humanURL: https://www.twilio.com/docs/iam/api/account
  baseURL: https:/api.twilio.com
  tags:
    - Video
  properties:
    - type: X-documentation
      url: https://www.twilio.com/docs/iam/api/account
    - type: X-openapi
      url: https://raw.githubusercontent.com/twilio/twilio-oai/main/spec/yaml/twilio_accounts_v1.yaml

# Central Properties
common:

  - type: X-signup
    url: https://www.twilio.com/try-twilio
  - type: X-about
    url: https://www.twilio.com/en-us/company
  - type: X-support
    url: https://support.twilio.com/   
  - type: X-sdks
    url: https://www.twilio.com/docs/libraries    
  - type: X-status
    url: https://status.twilio.com/   
  - type: X-change-log
    url: https://www.twilio.com/en-us/changelog     
  - type: X-blog
    url: https://www.twilio.com/blog      
  - type: X-privacy
    url: https://www.twilio.com/en-us/legal/privacy  
  - type: X-terms-of-service
    url: https://www.twilio.com/en-us/legal/tos           

maintainers:
- FN: API Evangelist
  email: [email protected]

I have created an APIs.json for Stripe, which I will write a separate story about, but I really like the Twilio example. I feel like their approach not only shows the strength of APIs.json, it provides a template other API producers can follow. I mean, we all have talked about and emulated Twilio over the years, but this provides a simple machine-readable blueprint that anyone can follow. For me, it really is where the bar is for any public API program, demonstrating how to organize your APIs as well as the supporting building blocks for your consumers.