次の方法で共有

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 と非推奨のバージョンのスクリーンショット。

次のステップ

この記事では、DICOM サービスの API バージョン ポリシーについて説明しました。 DICOM サービスの詳細については、次を参照してください。

DICOM サービスの概要