Управление версиями API для службы DICOM

Статья
11/09/2024

Это справочное руководство содержит общие сведения о политиках версий API для службы DICOM®.

Указание версии REST API в запросах

Версия REST API должна быть явно указана в URL-адресе запроса, как показано в следующем примере:

<service_url>/v<version>/studies

Маршруты без версии не поддерживаются.

Поддерживаемые версии

В настоящее время поддерживаются следующие версии:

версия 1.0-prerelease
Версия 1
Версия 2

Документация OpenAPI для поддерживаемых версий можно найти по следующему URL-адресу:

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

Оператор соответствия DICOM

Все версии API DICOM соответствуют спецификациям DICOMweb™ Standard, но разные версии могут предоставлять различные API. Дополнительные сведения см. в конкретной версии инструкции соответствия.

Предварительные версии

Версия API с меткой prerelease указывает, что версия не готова для рабочей среды, и она должна использоваться только в средах тестирования. Эти конечные точки могут столкнуться с критическими изменениями без уведомления.

Увеличение версий

В настоящее время мы добавим только основную версию всякий раз, когда есть критическое изменение, которое считается не совместимым обратно.

Ниже приведены некоторые примеры критических изменений (приращение основной версии):

Переименование или удаление конечных точек.
Удаление параметров или добавление обязательных параметров.
Изменение кода состояния.
Удаление свойства в ответе или изменение типа ответа вообще. Это нормально добавить свойства в ответ.
Изменение типа свойства.
Поведение при изменении API, таких как изменения в бизнес-логике, используемой для выполнения foo, но теперь это делает бар.

Неразрывные изменения (версия не увеличивается):

Добавление свойств, допускающих значение NULL или имеющих значение по умолчанию.
Добавление свойств в модель отклика.
Изменение порядка свойств.

Заголовок в ответе

ReportApiVersions включен, что означает, что система возвращает заголовки, поддерживаемые API и api-нерекомендуемые версии при необходимости.

Поддерживаемые API-версии содержат список версий, которые поддерживаются для запрошенного API. Он возвращается только при вызове конечной точки, аннотированной с ApiVersion("<someVersion>").
api-deprecated-versions содержит список версий, которые не рекомендуется использовать для запрошенного API. Он возвращается только при вызове конечной точки, аннотированной с ApiVersion("<someVersion>", Deprecated = true).

Пример:

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

Примечание.

DICOM® является зарегистрированным товарным знаком Национальной ассоциации производителей электрических технологий для публикаций по стандартам, касающихся цифровых коммуникаций медицинской информации.

Поделиться через