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 バージョンを取得することもできます。 詳しくは、「メタデータ用 REST API エンドポイント」を参照してください。