数以百万计的开发人员每天都依赖 GitHub API——无论他们是构建自己的定制集成还是使用来自 GitHub Marketplace 的第三方应用程序。
我们知道提供稳定、一致的 API 体验绝对至关重要。我们不能也不会期望集成商在我们调整 API 时不断更新他们的集成。
同时，我们能够随着时间的推移改进 API 也很重要。如果 API 必须永远保持不变，那么我们就无法为 API 用户带来最新最好的产品功能、修复错误或改善开发人员体验。
我们可以在不对现有集成产生负面影响的情况下进行大部分更改（例如，引入新端点）。我们将这些称为非破坏性更改，并且我们每天都在进行更改。
但有时，我们需要进行重大更改，例如删除响应字段、使可选参数成为必需参数或完全删除端点。
十多年前，我们推出了 API 的第 3 版（“V3”）。它为我们提供了很好的服务，但我们还没有合适的工具和流程来进行偶尔的重大更改并为现有用户提供顺畅的迁移路径和充足的时间来升级他们的集成。
为了使我们能够在未来十年（甚至更久！）继续发展 API，我们正在为REST API引入基于日历的版本控制。
这篇文章将展示新的 API 版本控制系统将如何工作以及接下来会发生什么。
它是如何工作的——一个 60 秒的总结
每当我们需要对 REST API 进行重大更改时，我们都会发布一个新版本。前往我们的文档了解我们认为是破坏性和非破坏性的变化类型。
版本将根据发布日期命名。例如，如果我们在 2025 年 12 月 25 日发布了一个新版本，我们会将该版本称为2025-12-25.
当我们发布新版本时，以前的版本仍然可用，因此您不会被迫立即升级。
选择您要使用的版本很容易。您只需使用标头在逐个请求的基础上指定要使用的版本X-GitHub-Api-Version。
在我们的API 文档中，可以使用版本选择器选择要查看的文档版本。
我们只会将版本控制用于重大更改。非重大更改将继续在所有 API 版本中可用。
注意：基于日历的 API 版本控制仅适用于我们的 REST API。它不适用于我们的 GraphQL API 或 webhooks。
多久发布一次新版本，它们将持续多长时间？
当我们想要对 API 进行重大更改时，我们将发布一个新版本。
我们建议新的集成应该使用最新的 API 版本，现有的集成商应该保持他们的集成是最新的，但我们不会频繁地淘汰旧版本或强制用户升级。
当发布新的 REST API 版本时，我们承诺至少支持以前的版本两年（24 个月）。
两年后，我们保留停用某个版本的权利，但实际上，我们希望支持历史版本的时间比这长得多。当我们决定终止对旧版本的支持时，我们会在我们的博客上和通过电子邮件宣布。
我有一个与 REST API 的现有集成。这对我意味着什么？
现在不需要做任何事情。
我们采用了 GitHub API 的现有状态——已经在使用的——并将其称为版本2022-11-28。
我们鼓励集成商更新他们的集成以发送新的X-GitHub-Api-Version: 2022-11-28标头。版本2022-11-28与我们启动版本控制之前的 API 完全相同，因此无需对集成进行任何更改。
在接下来的几个月里，我们将发布另一个包含重大更改的版本。要移动到该版本，需要将X-GitHub-Api-Version标头指向该新版本，并确保集成适用于该版本中引入的更改。当然，我们将提供完整的变更日志和有关如何升级的说明。
后续步骤——以及今天可以做什么
如果与 REST API 集成，则应立即更新它以开始发送X-GitHub-Api-Version标头。
很快，我们将发布具有重大更改的 API 的过时版本。然后，每当我们发布新的 API 版本时，我们将：
- 将更新发布到 GitHub Changelog。
- 在GitHub REST API 文档中发布文档、有关更改的信息和升级指南。
- 向活跃的 GitHub.com 开发人员发送电子邮件，让他们了解新版本。
- 在 GitHub Enterprise Server 和 GitHub AE 的发行说明中包含提供 API 更改详细信息的注释。
我们还将推出工具来帮助组织和企业管理员跟踪他们的集成和使用中的 API 版本，从而轻松管理整个组织的升级过程。
