GitHub、REST APIに導入されているカレンダーベースのバージョニングシステムについて解説

　米GitHubは、REST APIに導入されているカレンダーベースのバージョニングシステムが、どのように機能しているかを11月28日（現地時間）付の公式ブログ投稿にて解説している。

　REST APIのバージョンは、リリースされた日付に基づいて命名されており、たとえば2025年12月25日に新バージョンをリリースする場合は、バージョンが2025-12-25となる。

　新バージョンがリリースされても、以前のバージョンは引き続き利用可能であり、X-GitHub-Api-Versionヘッダでリクエストごとに使用するバージョンを指定できる。また、バージョンピッカを用いて表示するAPIドキュメントのバージョンを選べる。

　なお、カレンダーベースのバージョン管理は重大な変更に対してのみ使用され、重大でない変更はすべての API バージョンで引き続き利用可能となっている。

　新バージョンのリリースは、APIに重大な変更を加えたい場合に行われ、古いバージョンを頻繁に廃止したり、ユーザーにアップグレードを強制したりすることはない。同社は、新たなREST APIバージョンがリリースされて、少なくとも2年間（24か月）はその前のバージョンをサポートすると述べており、リリースから2年後はバージョンを廃止する権利を留保するものの、実際にはより長い期間にわたって過去のバージョンのサポートを予定しているという。

　現在は、GitHub APIのバージョン2022-11-28が存在し、REST APIとの統合にはX-GitHub-Api-Version: 2022-11-28ヘッダの送信を推奨しており、バージョン2022-11-28はカレンダーベースのバージョン管理を開始する前のAPIとまったく同じなので、REST APIとの統合版に変更を加える必要はない。

　今後数か月以内に、重大な変更を含むREST APIの新バージョンをリリースする予定となっており、新バージョンへの移行にあたっては、X-GitHub-Api-Versionヘッダに新バージョンを指定し、新バージョンで導入された変更でREST APIとの統合版が機能することを確認する必要がある。

　すでにREST APIとの統合を行っている場合は、直ちに更新してX-GitHub-Api-Versionヘッダの送信をすることが推奨される。今後、新たなAPIバージョンがリリースされた場合は、

• GitHub Changelogへの更新の投稿
• GitHub REST API docsにおけるドキュメント、変更に関する情報、アップグレードガイドの公開
• アクティブなGitHub.com開発者へのメールによる新バージョンリリースの通知
• GitHub Enterprise ServerとGitHub AEのリリースノートへの、APIに対する変更の詳細を記載

を行っていく。

　あわせて、組織および企業の管理者がREST APIとの統合と使用中のAPIバージョンを追跡するのに役立つツールをリリースし、組織全体でのアップグレードプロセスの管理を容易にする。