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™ 標準規格，但不同的版本可能會公開不同的 API。 如需詳細資訊，請參閱特定版本的一致性語句：

• DICOM 一致性語句 v1
• DICOM 一致性語句 v2

發行前版本

具有「發行前版本」標籤的 API 版本表示版本尚未準備好用於生產環境，而且應該只在測試環境中使用。 這些端點可能會發生中斷性變更，而不需注意。

版本如何遞增

我們目前只會在發生重大變更時遞增主要版本，這被視為與回溯相容。

以下是中斷性變更的一些範例（主要版本遞增）：

• 重新命名或移除端點。
• 拿掉參數或新增強制參數。
• 變更狀態代碼。
• 刪除回應中的屬性，或完全改變回應類型。 將屬性新增至回應是可以的。
• 變更屬性的類型。
• API 變更時的行為，例如商業規則中用來進行 foo 的變更，但現在會執行條形圖。

非重大變更（版本未遞增）：

• 新增可為 Null 或具有預設值的屬性。
• 將屬性新增至回應模型。
• 變更屬性的順序。

回應中的標頭

ReportApiVersions 已開啟，這表示系統會在適當時傳回標頭 api 支援的版本和 api-deprecated-versions。

• api 支援的版本會列出所要求 API 支援的版本。 只有在呼叫以 ApiVersion("<someVersion>")標註的端點時，才會傳回它。

• api-deprecated-versions 會列出已針對要求 API 淘汰的版本。 只有在呼叫以 ApiVersion("<someVersion>", Deprecated = true)標註的端點時，才會傳回它。

範例：

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

注意

DICOM® 是美國電氣製造商協會對於其與醫療資訊數位通訊相關的標準出版物的註冊商標。