API 互換性ポリシー

最終更新日 2023年04月03日(月)

この記事では、Platform API 上に構築されるサービスの互換性に対する Heroku の取り組みについて説明します。API に変更が導入されるしくみと、それらの変更の告知方法についても説明します。

バージョンとリソースの安定性

v3 は Platform API の現行バージョンであり、唯一サポートされているバージョンでもあります。

API の特定のバージョン内では、どの特定のリソース (/apps​、/account​、/apps/:id/addons​ など) にも指定されたレベルの安定性があります。リソースの安定性は、JSON スキーマ​の stability​ プロパティで指定されます。Platform API リファレンスドキュメント​にも記載されます。

リソースの安定性は、リソースに対して Heroku が行う変更 (ある場合) の内容と、変更の告知方法を指定します。以下に、可能性のある変更の種類について詳しく説明します。すべての変更は Heroku Changelog​ で告知されます。

安定性にはプロトタイプ、開発、本番の 3 つのレベルがあります。

プロトタイプ

プロトタイプリソースは実験的であり、大きな変更が想定されます。プロトタイプリソースはその後、本番に移行する場合としない場合があります。

  • 互換性のある変更と緊急の変更は事前の告知なしに実施できます
  • 破壊的な変更は 1 週間前に告知することで実施できます
  • 非推奨のリソースは、非推奨になった後も最低 1 か月間は利用できます

開発

開発リソースは作業が進行中ですが、大きな変更はめったに発生しません。開発リソースはその後、本番の安定性に移行する必要があります。

  • 互換性のある変更と緊急の変更は事前の告知なしに実施できます
  • 破壊的な変更は 1 か月前に告知することで実施できます
  • 非推奨のリソースは、非推奨になった後も最低 6 か月間は利用できます

本番

本番リソースは完成しており、大きな変更は今後発生しません。

  • 互換性のある変更と緊急の変更は事前の告知なしに実施できます
  • 破壊的な変更は発生しません。代わりに新しいメジャーバージョンが開発されます
  • 非推奨のリソースは、非推奨になった後も最低 12 か月間は利用できます

非推奨

非推奨のリソースでは、JSON スキーマに deprecated_at​ 日付プロパティがあり、API リファレンスドキュメントにも表示されます。非推奨のリソースは、非推奨になった後も、安定性ごとに義務付けられた期間中 (プロトタイプリソースは 1 か月、開発リソースは 6 か月、本番リソースは 12 か月) は少なくとも機能し続けます。非推奨のリソースの安定性が変わることはありません。

完全に無効になったリソースは、すべてのリクエストに対して HTTP 410 を返すようになります。

変更の種類

互換性のある変更

スコープが狭く、既存のメソッドのセマンティックスを無効化または変更する可能性はまずありません。

  • リソース、メソッド、属性の追加
  • ドキュメントの変更
  • 文書化されていない動作の変更

破壊的な変更

大きな影響を及ぼす場合があり、必要に応じて、移行パスを提供するための配慮がなされます。

  • 既存メソッドのセマンティックスの変更
  • リソース、メソッド、属性の削除

緊急の変更

大きな影響が生じる可能性があるものの、法令順守、セキュリティの脆弱性、または仕様違反のため避けられない変更です。

API バージョンの選択

現行の v3 バージョンの API を使用するには、リクエストでヘッダー Accept: application/vnd.heroku+json; version=3​ を渡します。

特定のリソースの安定性は、API の特定のバージョンに対していつでも 1 つだけです。つまり、/apps​ エンドポイントが v3 で本番の安定性である場合、v3 で /apps​ に対して “プロトタイプ” の作業が発生することはありません。

v3 で /apps​ エンドポイントが本番の安定性に達した後、Heroku でこのエンドポイントに対して大きな変更を導入する場合、その作業は新しい API バージョンである v4 で行われることなります。そのようなバージョンはまだ存在しませんが、登場した場合、正しいヘッダー Accept: application/vnd.heroku+json; version=4​ を渡すことによってアクセスできます。

将来の API バージョンでは、現在の API バージョンで利用可能なすべてのリソースがサポートされるかどうかは不確定であり、リソースの再編成または名前変更が行われる可能性もあります。つまり、将来の v4 API には /apps​ リソースが含まれるが /account​ リソースは含まれない可能性があります (後者に対するリクエストは HTTP 404 を返します)。特定の API バージョンでサポートされるリソースは、そのリソースの公開済み JSON スキーマを調べることでいつでも確認できます。

$ curl https://api.heroku.com/schema  -H "Accept: application/vnd.heroku+json; version=4"