API のバージョン管理について
GitHub Enterprise Server REST API はバージョン管理されています。 API バージョンの名前は、その API バージョンがリリースされた日付に基づいています。 たとえば、API バージョン 2022-11-28 は Mon, 28 Nov 2022 にリリースされました。
すべての破壊的変更は、新しい API バージョンでリリースされます。 破壊的変更とは、統合を破損する可能性のある変更のことです。 破壊的変更には次のようなものが含まれます。
- 操作全体を削除する
- パラメーターを削除または名前変更する
- 応答フィールドを削除または名前変更する
- 新しい必須パラメーターを追加する
- 以前に省略可能だったパラメーターを必須にする
- パラメーターまたは応答フィールドの型を変更する
- 列挙型の値を削除する
- 既存のパラメーターに新しい検証規則を追加する
- 認証または認可の要件を変更する
追加的な (破壊的でない) 変更は、サポートされているすべての API バージョンで使用できます。 追加的な変更とは、統合を破損しない変更のことです。 追加的な変更には次のようなものが含まれます。
- 操作を追加する
- 省略可能なパラメーターを追加する
- 省略可能な要求ヘッダーを追加する
- 応答フィールドを追加する
- 応答ヘッダーを追加する
- 列挙型の値を追加する
新しい REST API バージョンがリリースされた場合、以前の API バージョンは、新しい API バージョンのリリースから少なくとも 24 か月間はサポートされます。
GitHub Enterprise Server のバージョン管理と REST API のバージョン管理について
GitHub Enterprise Server のバージョンは、REST API のバージョンから切り離されています。 API のバージョンが GitHub Enterprise Server のバージョンに含まれている限り、GitHub Enterprise Server のバージョンをアップグレードしつつ、同じ REST API バージョンを維持できます。 同様に、選択する新しい REST API のバージョンが GitHub Enterprise Server のバージョンで使用できる限り、GitHub Enterprise Server のバージョンを更新せずに REST API のバージョンをアップグレードできます。
GitHub Enterprise Server のリリース ノートには、REST API のバージョンがサポートされなくなるタイミングが記載されます。 詳しくは、「リリース ノート」を参照してください。
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 バージョンを取得することもできます。 詳しくは、「メタデータ用 REST API エンドポイント」を参照してください。