DICOM 서비스에 대한 API 버전 관리

  • 아티클

이 참조 가이드에서는 DICOM 서비스에 대한 API 버전 정책에 대한 개요를 제공합니다.

요청에서 REST API 버전 지정

REST API의 버전은 다음 예제와 같이 요청 URL에 명시적으로 지정해야 합니다.

<service_url>/v<version>/studies

참고

버전이 없는 경로는 지원되지 않습니다.

지원되는 버전

현재 지원되는 버전은 다음과 같습니다.

  • v1.0-시험판
  • v1
  • v2

지원되는 버전에 대한 OpenAPI 문서는 다음 URL에서 찾을 수 있습니다.

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

DICOM 규칙 문

모든 버전의 DICOM API는 항상 DICOMweb™ 표준 사양을 준수하지만 버전이 다르면 다른 API가 노출될 수 있습니다. 자세한 내용은 규칙 문의 특정 버전을 참조하세요.

시험판 버전

레이블이 "시험판"인 API 버전은 버전이 프로덕션에 사용할 준비가 되지 않았으며 테스트 환경에서만 사용해야 했음을 나타냅니다. 이러한 엔드포인트는 예고 없이 호환성이 손상되는 변경이 발생할 수 있습니다.

버전 증가 방법

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

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

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

호환성이 손상되지 않는 변경 내용(버전이 증가하지 않음):

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

응답의 헤더

ReportApiVersions가 켜져 있으므로 적절한 경우 헤더 api-supported-version 및 api-deprecated-version을 반환합니다.

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

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

예제:

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

지원되고 사용되지 않는 API 버전의 스크린샷.

다음 단계

이 문서에서는 DICOM 서비스에 대한 API 버전 정책에 대해 알아보았습니다. DICOM 서비스에 대한 자세한 내용은

DICOM 서비스 개요