# API のバージョン

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

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

GitHub REST API はバージョン管理されています。 API バージョンの名前は、その API バージョンがリリースされた日付に基づいています。 たとえば、api バージョン `2026-03-10` は、 Tue, 10 Mar 2026でリリースされました。

破壊的変更とは、統合を破損する可能性のある変更のことです。 破壊的変更は、新しい API バージョンでリリースされます。 破壊的変更をリリースする前に、事前通知を行います。 破壊的変更には次のようなものが含まれます。

* 操作全体を削除する
* パラメーターの削除または名前変更
* 応答フィールドの削除または名前変更
* 新しい必須パラメーターの追加
* 以前に省略可能だったパラメーターを必須にする
* パラメーターまたは応答フィールドの型の変更
* 列挙型の値の削除
* 既存のパラメーターへの新しい検証規則の追加
* 認証または認可の要件の変更

追加的な (破壊的でない) 変更は、サポートされているすべての API バージョンで使用できます。 追加的な変更とは、統合を破損しない変更のことです。 追加的な変更には次のようなものが含まれます。

* 操作の追加
* 省略可能なパラメーターの追加
* 省略可能な要求ヘッダーの追加
* 応答フィールドの追加
* 応答ヘッダーの追加
* 列挙型の値の追加

新しい REST API バージョンがリリースされた場合、以前の API バージョンは、新しい API バージョンのリリースから少なくとも 24 か月間はサポートされます。

## API バージョンの指定

API バージョンを指定するには、`X-GitHub-Api-Version` ヘッダーを使用する必要があります。 次に例を示します。

```shell
curl --header "X-GitHub-Api-Version:2026-03-10" https://api.github.com/zen
```

`X-GitHub-Api-Version` ヘッダーのない要求では、既定で `2022-11-28` バージョンが使用されます。

サポートされなくなった API バージョンを指定すると、 `410 Gone` 応答が返されます。

## 新しい API バージョンへのアップグレード

新しい REST API バージョンにアップグレードする前に、新しい API バージョンの破壊的変更に関する変更ログを読んで、どのような破壊的変更が含まれているかを理解し、その特定の API バージョンにアップグレードする方法の詳細を確認する必要があります。 詳しくは、「[重大な変更](/ja/enterprise-cloud@latest/rest/about-the-rest-api/breaking-changes)」をご覧ください。

`X-GitHub-Api-Version` ヘッダーで新しい API バージョンを指定するように統合を更新する場合は、統合が新しい API バージョンで動作するために必要な変更を加える必要もあります。

統合が更新されたら、統合をテストして、新しい API バージョンで動作することを確認します。

## API バージョン 閉鎖

API バージョンは、新しい API バージョンがリリースされてから 24 か月間サポートされます。

バージョンはサポート期間内ですが、  閉鎖に近づいている間、 GitHub には、移行の準備に役立つ次のヘッダーが API 応答に含まれています。

* `Deprecation` — API バージョンが 閉鎖される日付。 [RFC 7231](https://tools.ietf.org/html/rfc7231#section-7.1.1.1) に従って HTTP 日付として書式設定されます。 例: `Wed, 27 Nov 2019 14:34:29 GMT`。 <!-- markdownlint-disable-line GHD046 -->
* `Sunset` — API バージョンが完全に削除される (引退) 日付。その後、要求は `410 Gone` 応答を返します。
  [RFC 8594 に](https://tools.ietf.org/html/rfc8594)従います。 例: `Fri, 27 Nov 2020 14:34:29 GMT`。 <!-- markdownlint-disable-line GHD046 -->

サポート ウィンドウが終了した後:

* 閉鎖 API バージョンを指定する要求は、`410 Gone`応答を受け取ります。
* API バージョンを指定しない要求は、 閉鎖 バージョンではなく、サポートされている次の最も古いバージョンに既定で設定されます。 バージョン管理されていない要求に依存している場合は、古いバージョンがサポートから削除されるため、動作の変更が観察される可能性があります。

新しい API バージョンへの移行の詳細については、 [重大な変更](/ja/enterprise-cloud@latest/rest/about-the-rest-api/breaking-changes) を参照してください。

## 標準バージョン管理の例外

まれに、 GitHub が通常の API バージョン管理の周期外で変更を加えます。 これらは、ほとんどのインテグレーターの標準バージョン管理の保証を変更しない例外的な介入です。

### セキュリティ、可用性、信頼性に関する問題

重大なセキュリティの脆弱性、データ公開リスク、または重大な信頼性の問題では、通常のリリース スケジュール外の変更が必要になる場合があります。
GitHub は、スケジュールされていない API バージョンのリリース、サポートされているバージョンへのバックポート修正、またはまれなケースで、ユーザーとプラットフォームの整合性を保護するために既存のバージョンに破壊的変更を加える可能性があります。

GitHub は、リリース ノート、変更ログ、および変更内容とその理由を説明する直接の通信を通じて、このような変更を伝達します。 可能な場合は、事前通知を行います。 必要に応じて、事前の通知なしに直ちに措置を講じることがあります。

### 使用率の低いサービス

使用率が非常に低い特定のサービスでは、 GitHub は標準のバージョン管理プロセス以外の機能を非推奨にする可能性があります。 このような場合、 GitHub は意図を伝え、影響を受けるインテグレーターに直接連絡します。

## サポートされる API バージョン

現在、次の REST API バージョンがサポートされています。

| API バージョン    | サポート終了日           |
| ------------ | ----------------- |
| `2026-03-10` | Not yet scheduled |
| `2022-11-28` | March 10, 2028    |

API 要求を行い、サポートされているすべての API バージョンを取得することもできます。 詳しくは、「[メタデータ用 REST API エンドポイント](/ja/enterprise-cloud@latest/rest/meta/meta#get-all-api-versions)」をご覧ください。