About API versioning
The GitHub Enterprise Server REST API is versioned. The API version name is based on the date when the API version was released. For example, the API version 2022-11-28 was released on Mon, 28 Nov 2022.
Any breaking changes will be released in a new API version. Breaking changes are changes that can potentially break an integration. Breaking changes include:
- removing an entire operation
- removing or renaming a parameter
- removing or renaming a response field
- adding a new required parameter
- making a previously optional parameter required
- changing the type of a parameter or response field
- removing enum values
- adding a new validation rule to an existing parameter
- changing authentication or authorization requirements
Any additive (non-breaking) changes will be available in all supported API versions. Additive changes are changes that should not break an integration. Additive changes include:
- adding an operation
- adding an optional parameter
- adding an optional request header
- adding a response field
- adding a response header
- adding enum values
When a new REST API version is released, the previous API version will be supported for at least 24 more months following the release of the new API version.
About GitHub Enterprise Server versioning and REST API versioning
GitHub Enterprise Server versions are decoupled from REST API versions. You can upgrade your GitHub Enterprise Server version but keep the same REST API version, as long as the API version is included in the GitHub Enterprise Server version. Similarly, you can upgrade your REST API version without updating your GitHub Enterprise Server version, as long as the new REST API version you choose is available for your GitHub Enterprise Server version.
The GitHub Enterprise Server release notes will state when a REST API version is no longer supported. For more information, see Release notes.
Specifying an API version
You should use the X-GitHub-Api-Version header to specify an API version. For example:
curl --header "X-GitHub-Api-Version:2022-11-28" https://api.github.com/zen
Requests without the X-GitHub-Api-Version header will default to use the 2022-11-28 version.
If you specify an API version that is no longer supported, you will receive a 400 error.
Upgrading to a new API version
Before upgrading to a new REST API version, you should read the changelog of breaking changes for the new API version to understand what breaking changes are included and to learn more about how to upgrade to that specific API version. For more information, see Breaking changes.
When you update your integration to specify the new API version in the X-GitHub-Api-Version header, you'll also need to make any changes required for your integration to work with the new API version.
Once your integration is updated, test your integration to verify that it works with the new API version.
Supported API versions
The following REST API versions are currently supported:
2022-11-28
You can also make an API request to get all of the supported API versions. For more information, see REST API endpoints for meta data.