Udostępnij za pośrednictwem

Obsługa wersji interfejsu API dla usługi DICOM

  • Artykuł

Ten przewodnik referencyjny zawiera omówienie zasad wersji interfejsu API dla usługi DICOM®.

Określanie wersji interfejsu API REST w żądaniach

Wersja interfejsu API REST musi być jawnie określona w adresie URL żądania, jak w poniższym przykładzie:

<service_url>/v<version>/studies

Trasy bez wersji nie są obsługiwane.

Obsługiwane wersje

Obecnie obsługiwane wersje to:

  • Wersja wstępna w wersji 1.0
  • v1
  • v2

Dokument interfejsu OpenAPI dla obsługiwanych wersji można znaleźć pod następującym adresem URL:

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

Instrukcja zgodności z diCOM

Wszystkie wersje interfejsów API DICOM są zgodne ze specyfikacjami DICOMweb™ Standard, ale różne wersje mogą uwidaczniać różne interfejsy API. Aby uzyskać szczegółowe informacje, zobacz określoną wersję instrukcji zgodności:

Wersje wstępne

Wersja interfejsu API z etykietą "wersja wstępna" wskazuje, że wersja nie jest gotowa do produkcji i powinna być używana tylko w środowiskach testowych. Te punkty końcowe mogą napotkać zmiany powodujące niezgodność bez powiadomienia.

Jak wersje są zwiększane

Obecnie zwiększamy wersję główną tylko wtedy, gdy występuje zmiana powodująca niezgodność, która jest uważana za niezgodną z poprzednimi wersjami.

Oto kilka przykładów zmian powodujących niezgodność (wersja główna jest zwiększana):

  • Zmiana nazwy lub usuwanie punktów końcowych.
  • Usuwanie parametrów lub dodawanie obowiązkowych parametrów.
  • Zmiana kodu stanu.
  • Usunięcie właściwości w odpowiedzi lub zmianę typu odpowiedzi. Dobrze jest dodać właściwości do odpowiedzi.
  • Zmiana typu właściwości.
  • Zachowanie w przypadku zmiany interfejsu API, takich jak zmiany w logice biznesowej używane do wykonywania foo, ale teraz nie działa.

Zmiany nierozwiązane (wersja nie jest zwiększana):

  • Dodanie właściwości, które są dopuszczane do wartości null lub mają wartość domyślną.
  • Dodawanie właściwości do modelu odpowiedzi.
  • Zmiana kolejności właściwości.

Nagłówek w odpowiedzi

Funkcja ReportApiVersions jest włączona, co oznacza, że system zwraca nagłówki api-supported-versions i api-przestarzałe wersje, jeśli jest to konieczne.

  • Wersje obsługiwane przez interfejs API wyświetla listę obsługiwanych wersji dla żądanego interfejsu API. Jest zwracany tylko podczas wywoływania punktu końcowego z adnotacją .ApiVersion("<someVersion>")

  • Wersje przestarzałe interfejsu API zawierają listę wersji przestarzałych dla żądanego interfejsu API. Jest zwracany tylko podczas wywoływania punktu końcowego z adnotacją .ApiVersion("<someVersion>", Deprecated = true)

Przykład:

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

Zrzut ekranu przedstawiający obsługiwane i przestarzałe wersje interfejsu API.

Uwaga

DICOM® jest zastrzeżonym znakiem towarowym National Electrical Manufacturers Association for its Standards publikacji odnoszących się do cyfrowej komunikacji informacji medycznych.