关于 API 版本控制
GitHub REST API 已版本化。 API 版本名称基于 API 版本的发布日期。 例如，API 版本2026-03-10已于Tue, 10 Mar 2026发布。
破坏性变更是可能会影响集成的变更。 重大更改将在新的 API 版本中发布。 在发布重大更改之前，我们会提前通知。 重大变更包括：
- 删除整个业务操作
- 删除或重命名参数
- 删除或重命名响应字段
- 添加新的必需参数
- 将以前的可选参数设置为必需参数
- 更改参数或响应字段的类型
- 删除枚举值
- 向现有参数添加新的验证规则
- 更改身份验证或授权要求
所有支持的 API 版本都将包含所有增量（不影响现有功能的）更改。 增量更改是不应破坏集成的更改。 附加更改包括：
- 添加操作
- 添加可选参数
- 添加可选请求头
- 添加响应字段
- 添加响应头
- 添加枚举值
当发布新版本的 REST API 时，先前的 API 版本将在新版本发布后至少再支持24个月。
关于 GitHub Enterprise Server 版本控制和 REST API 版本控制
GitHub Enterprise Server 版本与 REST API 版本独立分开。 你可以升级版本 GitHub Enterprise Server ，但保留相同的 REST API 版本，只要 API 版本包含在 GitHub Enterprise Server 版本中。 同样，只要你选择的新 REST API 版本可用于GitHub Enterprise Server版本，就可以升级 REST API 版本，而无需更新GitHub Enterprise Server版本。
不再支持 REST API 版本时， GitHub Enterprise Server 发行说明将声明。 有关详细信息，请参阅“发行说明”。
指定 API 版本
应使用 X-GitHub-Api-Version 标头指定 API 版本。 例如：
curl --标头 "X-GitHub-Api-Version:2022-11-28" https://api.github.com/zen
没有 X-GitHub-Api-Version 标头的请求将默认使用 2022-11-28 版本。
如果指定不再受支持的 API 版本，将收到 410 Gone 响应。
升级到新的 API 版本
在升级到新的 REST API 版本之前，应阅读新 API 版本的中断性变更日志，以了解包含哪些中断性变更，并详细了解如何升级到该特定 API 版本。 有关详细信息，请参阅“重大更改”。
更新集成以在 X-GitHub-Api-Version 标头中指定新的 API 版本时，还需要对集成进行任何更改才能使用新的 API 版本。
更新集成后，测试集成以验证它是否适用于新 API 版本。
API 版本 已弃用
发布较新的 API 版本后，API 版本支持 24 个月。
虽然某个版本在支持窗口内，但即将结束支持周期已弃用时，GitHub 会在 API 响应中包含以下标头，以帮助你为迁移做好准备：
Deprecation— API 版本将于 已弃用，日期采用 RFC 7231 格式的 HTTP 日期格式。 例如：Wed, 27 Nov 2019 14:34:29 GMT。Sunset— API 版本将完全删除的日期（停用之后，请求将返回410 Gone响应）。 遵循 RFC 8594。 例如：Fri, 27 Nov 2020 14:34:29 GMT。
支持窗口结束后：
- 指定 已弃用 API 版本的请求会收到
410 Gone响应。 - 未指定 API 版本的请求默认为下一个最早支持的版本，而不是版本 已弃用 。 如果依赖于未转换的请求，你可能会发现行为更改，因为旧版本已从支持中删除。
有关迁移到较新的 API 版本的详细信息，请参阅 重大更改。
标准版本控制例外
在极少数情况下， GitHub 可能会在正常 API 版本控制节奏之外进行更改。 这些是特殊干预，不会改变大多数集成商的标准版本控制保证。
安全性、可用性和可靠性问题
严重安全漏洞、数据泄露风险或严重可靠性问题可能需要在正常发布计划之外进行更改。 GitHub 可能会发布计划外的 API 版本，向支持的版本回移植修补程序，或者在极少数情况下，对现有版本进行严重更改，以保护用户和平台的完整性。
GitHub 将通过发行说明、更改日志和直接通信来传达此类更改，说明更改的原因和原因。 如果可行，将提供提前通知。 如果需要，可以立即采取措施，而无需事先通知。
低使用率服务
对于使用率非常低的某些服务， GitHub 可能会在标准版本控制过程之外弃用功能。 在这些情况下， GitHub 将传达意向并直接与受影响的集成商联系。
支持的 API 版本
目前支持以下 REST API 版本。
| API 版本 | 支持结束日期 |
|---|---|
2022-11-28 | March 10, 2028 |
还可以发出 API 请求以获取所有受支持的 API 版本。 有关详细信息，请参阅“元数据的 REST API 端点”。