Správa verzí rozhraní API pro službu DICOM

Článek
11/09/2024

Tato referenční příručka obsahuje přehled zásad verzí rozhraní API pro službu DICOM®.

Určení verze rozhraní REST API v požadavcích

Verze rozhraní REST API musí být explicitně zadaná v adrese URL požadavku, jak je znázorněno v následujícím příkladu:

<service_url>/v<version>/studies

Trasy bez verze nejsou podporované.

Podporované verze

V současné době jsou podporované verze:

v1.0-prerelease
v1
v2

Dokument OpenAPI pro podporované verze najdete na následující adrese URL:

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

DiCOM – příkaz – shoda

Všechny verze rozhraní API DICOM odpovídají specifikacím DICOMweb™ Standard, ale různé verze můžou vystavit různá rozhraní API. Podrobnosti najdete v konkrétní verzi příkazu shody:

Předběžné verze

Verze rozhraní API s popiskem "předběžná verze" značí, že verze není připravená pro produkční prostředí a měla by se používat jenom v testovacích prostředích. U těchto koncových bodů můžou docházet k zásadním změnám bez předchozího upozornění.

Způsob zvýšení verzí

V současné době navyšujeme hlavní verzi vždy, když dojde k zásadní změně, která se považuje za nekompatibilní.

Tady je několik příkladů zásadních změn (hlavní verze se zvýší):

Přejmenování nebo odebrání koncových bodů
Odebrání parametrů nebo přidání povinných parametrů
Změna stavových kódů
Odstranění vlastnosti v odpovědi nebo změna typu odpovědi Je v pořádku přidat do odpovědi vlastnosti.
Změna typu vlastnosti
Chování, když se rozhraní API změní, například změny v obchodní logice, které se používají k akci, ale teď se změní na pruh.

Neprolomené změny (verze se nezvýšila):

Přidání vlastností, které mají možnou hodnotu null nebo mají výchozí hodnotu
Přidání vlastností do modelu odpovědi
Změna pořadí vlastností

Hlavička v odpovědi

ReportApiVersions je zapnutý, což znamená, že systém v případě potřeby vrátí hlavičky api-supported-versions a api-deprecated-versions.

Verze podporované rozhraní api uvádí, které verze jsou podporované pro požadované rozhraní API. Vrátí se pouze při volání koncového bodu s poznámkami ApiVersion("<someVersion>").
Seznam zastaralých verzí rozhraní API, které verze byly pro požadované rozhraní API zastaralé. Vrátí se pouze při volání koncového bodu s poznámkami ApiVersion("<someVersion>", Deprecated = true).

Příklad:

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

Poznámka:

DICOM® je registrovaná ochranná známka asociace National Electrical Manufacturers Association pro publikace standardů týkající se digitální komunikace s lékařskými informacemi.

Sdílet prostřednictvím