Skip to content
This repository has been archived by the owner on Jul 15, 2024. It is now read-only.
/ sendgrid-oai Public archive

SendGrid's Open API specification for the v3 API

License

Notifications You must be signed in to change notification settings

sendgrid/sendgrid-oai

Repository files navigation

SendGrid Logo

Test and Deploy Twitter Follow GitHub contributors MIT licensed

This is an OpenAPI representation of the SendGrid v3 Web API.

If you have an interesting use case for these files or have a request, please create an issue.

Project Status

This repository contains several OpenAPI representations of the Twilio SendGrid API.

  1. Existing specification files that have been available for an extended time.
  2. An OpenAPI v3.1 file that represents the future of this repository.

Existing OpenAPI files

The following OpenAPI representations are available in this repository to support any existing projects that may rely on them.

Swagger v2

All Swagger v2 representations of the Twilio SendGrid API describe the entirety of the API in a single JSON or YAML file.

OpenAPI v3

The OpenAPI v3 representation of the Twilio SendGrid API located in the file below describes the entirety of the SendGrid API in a single JSON file.

Though this file should not be relied on going forward, it was used as a starting point for the oas_v3.json file that will be maintained going forward.

Future development and support

OpenAPI v3.1 Beta status

The OpenAPI v3.1 spec defined in oas_v3.json is currently in Beta.

This specification file is usable but subject to change. It may not accurately represent all Twilio SendGrid API features at this time. For this reason, the existing Swagger v2 and OpenAPI v3 files will remain in this repository. In the event that we remove any OpenAPI files, Twilio SendGrid will communicate the changes in advance.

If you've identified a mismatch between Twilio SendGrid's API behavior and this specification, please open an issue.

OpenAPI v3.1 details

Linting

The oas_v3.json specification file and its linked files are linted using Spectral. You can find the Spectral version in this repository's package.json file.

File organization

The oas_v3.json file uses JSON Reference syntax and JSON Pointer syntax to construct the full specification from the definitions in the spec directory. The specification has been segmented this way to improve maintainability.

Each directory in the spec directory is organized to match the structure of the Twilio SendGrid API reference. This structure is subject to change without notice while the specification remains in Beta.

Contributions

The OpenAPI v3.1 specification is generated internally by Twilio SendGrid tooling. For this reason, we cannot accept Pull Requests against any of the future-facing files: oas_v3.json, all files in the /spec directory.

We do, however, welcome any Issues you report, and we will gladly add them to our internal backlog.

Announcements

  • This project contains a Beta version of Twilio SendGrid's OpenAPI v3.1 specification as of Q1 2022. The spec may not be accurate at this stage; it is in active development.

All the updates to this project are documented in our CHANGELOG.

How to Contribute

We encourage contributions to our projects, please see our CONTRIBUTING guide for more details.

Quick links:

About

sendgrid-oai is maintained and funded by Twilio SendGrid, Inc. The names and logos for sendgrid-oai are trademarks of Twilio SendGrid, Inc.

License

The MIT License (MIT)