Správa verzí rozhraní API pro službu DICOM
Tato referenční příručka poskytuje 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ě zadána v adrese URL požadavku jako v následujícím příkladu:
<service_url>/v<version>/studies
Poznámka
Trasy bez verze nejsou podporovány.
Podporované verze
Aktuálně podporované verze jsou:
- Předběžná verze v1.0
- v1
- v2
Dokument OpenAPI pro podporované verze najdete na následující adrese URL:
<service_url>/v<version>/api.yaml
Prohlášení o shodě dicom
Všechny verze rozhraní DICOM API budou vždy odpovídat specifikacím standardu DICOMweb™, ale různé verze můžou vystavit různá rozhraní API. Podrobnosti najdete v konkrétní verzi prohlášení o shodě:
Předběžné verze
Verze rozhraní API s popiskem "předběžná verze" označuje, že verze není připravená pro produkční prostředí a měla by se používat pouze v testovacích prostředích. U těchto koncových bodů může bez předchozího upozornění docházet k zásadním změnám.
Jak se verze navyšují
V současné době navyšujeme hlavní verzi vždy, když dojde ke změně způsobující chybu, což se považuje za zpětně nekomppatibilní.
Níže je uvedeno několik příkladů změn způsobujících chybu (hlavní verze je zvyšovat):
- 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 vůbec, ale přidání vlastností do odpovědi je v pořádku.
- Změna typu vlastnosti
- Chování v případě, že se v rozhraní API mění, například změny obchodní logiky, se dřív používalo k akci typu foo, ale teď dělá bar.
Zásadní změny (verze se nezvýšila):
- Přidání vlastností, které mohou mít 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
Je zapnutá možnost ReportApiVersions, což znamená, že v případě potřeby vrátíme hlavičky api-supported-versions a api-deprecated-versions.
verze api-supported-versions zobrazí seznam podporovaných verzí pro požadované rozhraní API. Vrátí se pouze při volání koncového bodu s poznámkou
ApiVersion("<someVersion>").api-deprecated-versions zobrazí seznam verzí, které byly pro požadované rozhraní API zastaralé. Vrátí se pouze při volání koncového bodu s poznámkou
ApiVersion("<someVersion>", Deprecated = true).
Příklad:
[ApiVersion("1")]
[ApiVersion("1.0-prerelease", Deprecated = true)]
Další kroky
V tomto článku jste se dozvěděli o zásadách verzí rozhraní API pro službu DICOM. Další informace o službě DICOM najdete v tématu