GitHub开始以日期命名REST API版本号

GitHub更新API版本控制的命名方法,以日期来命名版本号,像是在2025年12月25日发布的新版本,该版本就会被命名成2025-12-25,这项规则仅适用于具有重大变更的版本。这项基于日期的版本控制方法,让官方可以不断发展API,但同时有提供顺畅的搬迁路径和充足的时间,供用户进行集成。

目前GitHub API有数百万用户,包含开发者自建,以及来自GitHub Marketplace第三方应用程序的集成。API随着时间推移会出现变化,势必加入更新的产品功能、修复错误或是改善开发人员体验,但另一方面,在API更改时,官方无法期待API用户会不断地更新集成。

API变更分成两种,一种是不会对现有集成产生负面影响的情况,称为非破坏性变更,另一种破坏性变更,则会出现删除回应字段、参数变更或是完全删除端点等情况。GitHub在10年前发布API V3,这个版本虽然运行良好,但是未提供适当的工具和流程,无法在进行重大更新时支持现有用户顺畅的搬迁。

GitHub建议所有集成都要使用最新的API版本,官方提到,他们通常并不会频繁地淘汰旧版本,或是强制用户升级,当有新的REST API版本发布时,也会至少支持旧版本2年。当新版本升级,之前的版本同样可用,用户不会被强迫升级,并且可以使用X-GitHub-Api-Version标头要求指定使用的版本,来选择所要使用的版本。

正在使用GitHub REST API的开发者,目前不需要采取任何行动,GitHub API的现有状态,也就是用户当前使用的版本为2022-11-28,但官方鼓励用户更新集成,并且主动发送X-GitHub-Api-Version: 2022-11-28标头。不过,GitHub在接下来几个月内,就会发布另一个包含重大更新的版本,要搬迁到该版本,就会需要使用X-GitHub-Api-Version标头并且指向新版本。

目前这个以日期为基础的API版本号控制方法仅适用于REST API,在GraphQL API和webhooks则未提供。