Skip to main content

API のバージョン

REST API に対して要求を行うたびに使用する、REST API バージョンを指定する方法について説明します。

API のバージョン管理について

GitHub 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 --header "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 バージョンを取得することもできます。 詳しくは、「Meta」を参照してください。