はじめに

バージョニングと廃止

URLのメジャーバージョン、互換性のある追加、非推奨の通知、提供終了までの期間について説明します。

安定したメジャーバージョンのパス

顧客の連携では、URLにメジャーバージョンを含めます。現在は/api/v1です。日付ベースのOpenAPIのinfo.versionは、そのメジャーバージョン内で公開されている正確な仕様を識別します。

互換性のある変更

SendHQはv1の範囲内で、任意のリクエストフィールド、レスポンスフィールド、スキーマが許す範囲での列挙値、新しい操作を追加することがあります。クライアントは未知のレスポンスフィールドを無視し、スキーマに明記されていない限り、列挙型を恒久的に固定されたものとして扱わないようにしてください。

破壊的変更

リクエスト、レスポンス、認証、動作に破壊的な変更を加える場合は、/api/v2のような新しいメジャーバージョンのパス、移行ドキュメント、告知された移行期間が必要です。現在のv1 APIは非推奨ではありません。

非推奨化と提供終了

バージョンが非推奨になった場合、SendHQは代替手段と移行手順をドキュメント化し、該当する場合はDeprecationヘッダーとSunsetヘッダーを返します。非推奨になったバージョンは、公表された非推奨化の日付から少なくとも90日間は引き続き利用できます。ただし、運用を続けることで緊急のセキュリティ上または法的なリスクが生じる場合は除きます。