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 版本。 例如：

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 版本。 有关详细信息，请参阅“重大更改”。

更新集成以在 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 版本支持结束日期
2026-03-10Not yet scheduled
2022-11-28March 10, 2028

还可以发出 API 请求以获取所有受支持的 API 版本。 有关详细信息，请参阅“元数据的 REST API 端点”。