バージョニングと非推奨化

URL major versioning

公開 API routes は URL で versioning されます。最初の public major は /api/v1/ です。

https://api.voiceagent.example/api/v1/agents

API keys は version-neutral です。vak_ key は workspace を認証し、URL path が API major を選択します。

legacy path の sunset

/api/agents のような version なしの legacy public paths は、互換性のための alias にすぎません。これらは 2026-11-04 に sunset する予定です。

legacy public aliases の response には deprecation headers が含まれます。

Deprecation: true
Sunset: Sun, 04 Nov 2026 00:00:00 GMT

新しいパートナー連携では /api/v1/ を使用し、version なしの /api/... paths を前提に実装しないでください。

非推奨化ポリシー

Tier A public API の breaking changes には、少なくとも 183 calendar days の事前通知が必要です。 notice period 中は、承認済みの security、legal、abuse、vendor-shutdown、data-integrity exception が適用されない限り、deprecated behavior は利用可能なまま維持されます。

breaking change には、文書化された paths、fields、statuses、error codes、authentication requirements、error envelope、pagination contract の削除または名称変更が含まれます。

ヘッダーの仕組み

deprecation response では、RFC 9745 の標準 Deprecation header と RFC 8594 の Sunset header を使用します。将来の formal deprecations では、migration または changelog documentation への Link header も含める必要があります。

Deprecation: @1780272000
Sunset: Tue, 01 Dec 2026 00:00:00 GMT
Link: <https://api-docs.voiceagent.example/changelog.html>; rel="deprecation"; type="text/html"

変更履歴

公開 changelog には、release notes、deprecations、sunset dates、replacements、 breaking-change notes が記録されます。変更履歴 を参照してください。