# API 版本

了解如何指定在向 REST API 发出请求时要使用的 REST API 版本。

## 关于 API 版本控制

GitHub REST API 已版本化。 API 版本名称基于 API 版本的发布日期。 例如，API 版本`2026-03-10`已于Tue, 10 Mar 2026发布。

破坏性变更是可能会影响集成的变更。 重大更改将在新的 API 版本中发布。 在发布重大更改之前，我们会提前通知。 重大变更包括：

* 删除整个业务操作
* 删除或重命名参数
* 删除或重命名响应字段
* 添加新的必需参数
* 将以前的可选参数设置为必需参数
* 更改参数或响应字段的类型
* 删除枚举值
* 向现有参数添加新的验证规则
* 更改身份验证或授权要求

所有支持的 API 版本都将包含所有增量（不影响现有功能的）更改。 增量更改是不应破坏集成的更改。 附加更改包括：

* 添加操作
* 添加可选参数
* 添加可选请求头
* 添加响应字段
* 添加响应头
* 添加枚举值

当发布新版本的 REST API 时，先前的 API 版本将在新版本发布后至少再支持24个月。

## 指定 API 版本

应使用 `X-GitHub-Api-Version` 标头指定 API 版本。 例如：

```shell
curl --标头 "X-GitHub-Api-Version:2026-03-10" https://api.github.com/zen
```

没有 `X-GitHub-Api-Version` 标头的请求将默认使用 `2022-11-28` 版本。

如果指定不再受支持的 API 版本，将收到 `410 Gone` 响应。

## 升级到新的 API 版本

在升级到新的 REST API 版本之前，应阅读新 API 版本的中断性变更日志，以了解包含哪些中断性变更，并详细了解如何升级到该特定 API 版本。 有关详细信息，请参阅“[重大更改](/zh/rest/about-the-rest-api/breaking-changes)”。

更新集成以在 `X-GitHub-Api-Version` 标头中指定新的 API 版本时，还需要对集成进行任何更改才能使用新的 API 版本。

更新集成后，测试集成以验证它是否适用于新 API 版本。

## API 版本 关闭

发布较新的 API 版本后，API 版本支持 24 个月。

当一个版本仍处于支持窗口期内但已接近 关闭，GitHub 会在 API 响应中包含以下标头，以帮助你为迁移做好准备：

* `Deprecation` – API 版本将进入 关闭 阶段的日期，格式为符合 [RFC 7231](https://tools.ietf.org/html/rfc7231#section-7.1.1.1) 标准的 HTTP 日期。 例如： `Wed, 27 Nov 2019 14:34:29 GMT`。 <!-- markdownlint-disable-line GHD046 -->
* `Sunset` — API 版本将完全删除的日期（退休之后，请求将返回 `410 Gone` 响应）。 遵循 [RFC 8594](https://tools.ietf.org/html/rfc8594)。 例如： `Fri, 27 Nov 2020 14:34:29 GMT`。 <!-- markdownlint-disable-line GHD046 -->

支持窗口结束后：

* 指定 关闭 API 版本的请求会收到 `410 Gone` 响应。
* 未指定 API 版本的请求默认为下一个最早支持的版本，而不是版本 关闭 。 如果你依赖未进行版本管理的请求，随着旧版本的支持停止，你可能会观察到行为变化。

有关迁移到较新的 API 版本的详细信息，请参阅 [重大更改](/zh/rest/about-the-rest-api/breaking-changes)。

## 标准版本控制例外

在极少数情况下， GitHub 可能会在正常 API 版本控制节奏之外进行更改。 这些是特殊干预，不会改变大多数集成商的标准版本控制保证。

### 安全性、可用性和可靠性问题

严重安全漏洞、数据泄露风险或严重可靠性问题可能需要在正常发布计划之外进行更改。
GitHub 可能会发布计划外的 API 版本，向支持的版本回移植修补程序，或者在极少数情况下，对现有版本进行严重更改，以保护用户和平台的完整性。

GitHub 将通过发行说明、更改日志和直接通信来传达此类更改，说明更改的原因和原因。 如果可行，将提供提前通知。 如果需要，可以立即采取措施，而无需事先通知。

### 低使用率服务

对于使用率非常低的某些服务， GitHub 可能会在标准版本控制过程之外弃用功能。 在这些情况下， GitHub 将传达意向并直接与受影响的集成商联系。

## 支持的 API 版本

目前支持以下 REST API 版本。

| API 版本       | 支持结束日期            |
| ------------ | ----------------- |
| `2026-03-10` | Not yet scheduled |
| `2022-11-28` | March 10, 2028    |

还可以发出 API 请求以获取所有受支持的 API 版本。 有关详细信息，请参阅“[元数据的 REST API 端点](/zh/rest/meta/meta#get-all-api-versions)”。