コンテンツへスキップ

ecentic API バージョン管理。

バージョンはパスに含まれます。特定バージョンに固定した統合は、開発時の契約を維持し、予告なしに失うことはありません。

URLパスでのバージョン管理 · 180日前通知 · DeprecationおよびSunsetヘッダー

01

バージョンの仕組み

パス内の単一番号で管理し、互換性を壊す場合にのみ変更します。

固定されたリクエスト/レスポンスバージョン

現在のバージョンはv1で、/api/v1で提供されています。すべてのレスポンスはAPI-Versionヘッダーにもバージョンを返すため、リダイレクトやリンクを辿ったクライアントでも実際の接続先を確認できます。

同じバージョンに追加

追加的変更は同一バージョン内で提供されます。新しいエンドポイント、新しい任意リクエストフィールド、既存レスポンスへの新フィールド追加などです。不明なレスポンスフィールドはエラーではなく前方互換性として扱ってください。

新しいバージョンパスを開始

フィールド削除、名前変更、型の制限、既存値の意味変更は破壊的変更であり、古いバージョンの横に新しいバージョンパスとして提供されます。既存パス上で変更されることはありません。

02

廃止とサンセット

2つの標準ヘッダーと、それに対応できる十分な猶予期間を提供します。

クライアントへの通知内容を確認するにはヘッダーを選択してください。

非推奨を告知済み

バージョンは非推奨です

非推奨バージョンからのすべてのレスポンスにこのヘッダーが含まれます。RFC 9745 に基づいて非推奨が通知されます。

Deprecationヘッダー形式

ヘッダー値は例示であり、提供終了の告知ではありません。

03

バージョン管理されないもの

ディスカバリードキュメントは、それぞれが使用するプロトコルのバージョンに従います。

.well-knownディスカバリードキュメントは、ecentic APIバージョンではなく、それぞれが実装するプロトコルのバージョンで管理されます。UCPプロファイルはUCPバージョンを、MCPサーバーカードはプロトコルバージョンを持つ、といった形です。バージョンは常にドキュメント内部から取得するのが正しく、ecentic APIバージョンから推測するべきではありません。

ecentic API契約
/api/v1
API-Version: 1
Discoveryプロトコル契約
.well-known
ドキュメント内のバージョンを確認