次の方法で共有

DICOM サービスの API バージョン管理

  • [アーティクル]

このリファレンス ガイドでは、DICOM® サービスの API バージョン ポリシーの概要について説明します。

要求での REST API バージョンの指定

REST API のバージョンは、次の例のように、要求 URL で明示的に指定する必要があります。

<service_url>/v<version>/studies

バージョンのないルートはサポートされていません。

サポートされているバージョン

現時点では、次のバージョンがサポートされています。

  • v1.0-prerelease
  • v1
  • v2

サポートされているバージョンの OpenAPI ドキュメントは、次の URL にあります。

<service_url>/v<version>/api.yaml

DICOM 適合性宣言書

DICOM API のすべてのバージョンは DICOMweb™ Standard 仕様に準拠していますが、バージョンが異なると、異なる API が公開される場合があります。 詳細については、準拠ステートメントの特定のバージョンを参照してください。

プレリリース バージョン

"プレリリース" というラベルが付いた API バージョンは、バージョンが運用環境に対応できないことを示し、テスト環境でのみ使用する必要があることを示します。 これらのエンドポイントでは、予告なしに重大な変更が発生する可能性があります。

バージョンの増分方法

現在、メジャー バージョンは、下位互換性がない重大な変更がある場合にのみインクリメントします。

破壊的変更の例をいくつか次に示します (メジャー バージョンがインクリメントされます)。

  • エンドポイントの名前変更または削除。
  • パラメーターの削除または必須パラメーターの追加。
  • 状態コードの変更。
  • 応答内のプロパティの削除、または応答の種類の変更。 応答にプロパティを追加してもかまいません。
  • プロパティの型の変更。
  • API が変更された場合の動作 (ビジネス ロジックの変更で、foo を実行していたものが、現在は bar を実行する場合など)。

非改行の変更 (バージョンはインクリメントされません):

  • null 許容または既定値を持つプロパティの追加。
  • 応答モデルへのプロパティの追加。
  • プロパティの順序の変更。

応答のヘッダー

ReportApiVersions は有効になっています。つまり、必要に応じて、api-supported-versions および api-deprecated-versions というヘッダーが返されます。

  • api-supported-versions には、要求された API でサポートされているバージョンが一覧表示されます。 これは、ApiVersion("<someVersion>") で注釈付けされたエンドポイントを呼び出す場合にのみ返されます。

  • api-deprecated-versions には、要求された API で非推奨となったバージョンが一覧表示されます。 これは、ApiVersion("<someVersion>", Deprecated = true) で注釈付けされたエンドポイントを呼び出す場合にのみ返されます。

例:

[ApiVersion("1")]
[ApiVersion("1.0-prerelease", Deprecated = true)]

サポートされている API と非推奨のバージョンのスクリーンショット。

Note

DICOM® は、医療情報のデジタル通信に関する標準出版物に関する米国電機工業会 (National Electrical Manufacturers Association) の登録商標です。