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 버전은 버전이 프로덕션에 사용할 준비가 되지 않았으며 테스트 환경에서만 사용해야 임을 나타냅니다. 이러한 엔드포인트는 예고 없이 호환성이 손상되는 변경이 발생할 수 있습니다.

버전 증가 방법

현재는 호환되지 않는 것으로 간주되는 호환성이 손상되는 변경이 있을 때마다 주 버전만 증가합니다.

다음은 호환성이 손상되는 변경의 몇 가지 예입니다(주 버전이 증가함).

• 엔드포인트 이름 바꾸기 또는 제거
• 매개 변수를 제거하거나 필수 매개 변수를 추가합니다.
• 상태 코드를 변경합니다.
• 응답에서 속성을 삭제하거나 응답 형식을 전혀 변경합니다. 응답에 속성을 추가해도 됩니다.
• 속성의 형식을 변경합니다.
• foo를 수행하는 데 사용되는 비즈니스 논리의 변경과 같이 API가 변경될 때 동작하지만 이제는 막대가 작동합니다.

변경되지 않는 변경 내용(버전이 증가하지 않음):

• nullable이거나 기본값이 있는 속성을 추가합니다.
• 응답 모델에 속성 추가
• 속성 순서 변경

응답의 헤더

ReportApiVersions가 켜져 있습니다. 즉, 시스템이 적절한 경우 헤더 api-supported-version 및 api-deprecated-version을 반환합니다.

• api 지원 버전에는 요청된 API에 대해 지원되는 버전이 나열됩니다. 주석이 추가된 엔드포인트를 호출할 때만 반환됩니다 ApiVersion("<someVersion>").

• api-deprecated-versions는 요청된 API에 대해 더 이상 사용되지 않는 버전을 나열합니다. 주석이 추가된 엔드포인트를 호출할 때만 반환됩니다 ApiVersion("<someVersion>", Deprecated = true).

예시:

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