Skip to main content

API 版本

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

关于 API 版本控制

GitHub Enterprise Cloud REST API 已进行版本控制。 API 版本名称基于 API 版本的发布日期。 例如,API 版本 2022-11-28 在 Mon, 28 Nov 2022 上发布。

任何中断性变更都将在新 API 版本中发布。 中断性变更是可能会中断集成的变更。 中断性变更包括:

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

所有支持的 API 版本都将提供任何附加(非中断性)更改。 附加更改是不应中断集成的更改。 附加更改包括:

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

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

指定 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 版本,将收到错误 400

升级到新的 API 版本

在升级到新的 REST API 版本之前,应阅读新 API 版本的中断性变更日志,以了解包含哪些中断性变更,并详细了解如何升级到该特定 API 版本。 有关详细信息,请参阅“重大更改”。

更新集成以在 X-GitHub-Api-Version 标头中指定新的 API 版本时,还需要对集成进行任何所需的更改,以便与新 API 版本一起工作。

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

支持的 API 版本

当前支持以下 REST API 版本:

2022-11-28

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