ecentic API バージョン管理。
バージョンはパスに含まれます。特定バージョンに固定した統合は、開発時の契約を維持し、予告なしに失うことはありません。
URLパスでのバージョン管理 · 180日前通知 · DeprecationおよびSunsetヘッダー
バージョンの仕組み
パス内の単一番号で管理し、互換性を壊す場合にのみ変更します。
現在のバージョンはv1で、/api/v1で提供されています。すべてのレスポンスはAPI-Versionヘッダーにもバージョンを返すため、リダイレクトやリンクを辿ったクライアントでも実際の接続先を確認できます。
同じバージョンに追加
追加的変更は同一バージョン内で提供されます。新しいエンドポイント、新しい任意リクエストフィールド、既存レスポンスへの新フィールド追加などです。不明なレスポンスフィールドはエラーではなく前方互換性として扱ってください。
新しいバージョンパスを開始
フィールド削除、名前変更、型の制限、既存値の意味変更は破壊的変更であり、古いバージョンの横に新しいバージョンパスとして提供されます。既存パス上で変更されることはありません。
廃止とサンセット
2つの標準ヘッダーと、それに対応できる十分な猶予期間を提供します。
クライアントへの通知内容を確認するにはヘッダーを選択してください。
非推奨を告知済み
バージョンは非推奨です
非推奨バージョンからのすべてのレスポンスにこのヘッダーが含まれます。RFC 9745 に基づいて非推奨が通知されます。
提供終了日を告知済み
提供終了日が確定
削除日が確定すると、このヘッダーもレスポンスに含まれます。RFC 8594 により、そのバージョンが応答を停止する日付が定義されます。
後継バージョンへのリンク
後継バージョンを特定
削除日に加えて、rel="successor-version" を持つ Link により、クライアントを後継バージョンへ案内します。
ヘッダー値は例示であり、提供終了の告知ではありません。
バージョン管理されないもの
ディスカバリードキュメントは、それぞれが使用するプロトコルのバージョンに従います。
.well-knownディスカバリードキュメントは、ecentic APIバージョンではなく、それぞれが実装するプロトコルのバージョンで管理されます。UCPプロファイルはUCPバージョンを、MCPサーバーカードはプロトコルバージョンを持つ、といった形です。バージョンは常にドキュメント内部から取得するのが正しく、ecentic APIバージョンから推測するべきではありません。
- ecentic API契約
- /api/v1
- API-Version: 1
- Discoveryプロトコル契約
- .well-known
- ドキュメント内のバージョンを確認