Repository files navigation

This repository containsOpenAPI descriptions forGitHub's REST API.

From theOpenAPI Specification:

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

As of the 1.1.4 release, this description is consideredstable and generally available.

Thedescriptions folder contains the 3.0 version of the description.Thedescriptions-next folder contains the 3.1 version of the description, and is subject to breaking changes on themain branch.

Each OpenAPI document is available in two formats:bundled anddereferenced.

• The bundled descriptions are single file artifacts that make usages of OpenAPIcomponents for reuse and portability. This is the preferred way of interacting with GitHub's OpenAPI description.
• Certain tools have poor support for references to components within the artifact. We highly encourage to look into tooling that supports referenced components, but since that's not always possible, we also provide a fully dereferenced version of the description as well, without any references.

We use various vendor extensions for concepts that are harder to express with OpenAPI components and/or are specific to GitHub. For more information on the extensions used in these description, check outextensions.md

• Not all headers are described in the OpenAPI documents, expect those to be added over time.
• Certain GitHub API resources use multi segment path parameters, which aren't supported by the OpenAPI specification. For the time being, we have annotated such parameters with ax-multi-segment extension. In general, URL encoding those parameters is a good idea.
• A lot of operations described in these documents are accessible through multiple paths. For the time being we have described the most common way to access these operations, but are working on a way to describe alias paths and/or describe all possible paths.
• This repository only contains the bundled and dereferenced versions of our REST API descriptions. We're looking into offering a fullyreferenced directory structure for easier browsing.

Because this description is used across GitHub's whole API development experience, we don't currently accept pull requests that directly modify the description. This repository is automatically kept up to date with the description used to validate GitHub API requests as well as powering contract tests. SeeCONTRIBUTING.md for more details.

If you've identified a mismatch between GitHub API's behavior and these descriptions, or found an issue with the format of a schema,please open an issue.

github/rest-api-description is licensed under theMIT license

You may contactopensource+rest-api-description@github.com with any questions related to this repository.