API-versionshantering för DICOM-tjänsten

Artikel
11/09/2024

Den här referensguiden ger dig en översikt över API-versionsprinciperna för DICOM-tjänsten®.

Ange version av REST API i begäranden

Versionen av REST-API:et måste uttryckligen anges i begärande-URL:en som i följande exempel:

<service_url>/v<version>/studies

Vägar utan version stöds inte.

Versioner som stöds

De versioner som stöds är för närvarande:

v1.0-prerelease
v1
v2

OpenAPI-dokumentet för de versioner som stöds finns på följande URL:

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

DICOM-överensstämmelseinstruklage

Alla versioner av DICOM-API:erna överensstämmer med DICOMweb™ Standard-specifikationerna, men olika versioner kan exponera olika API:er. Mer information finns i den specifika versionen av överensstämmelseutdraget:

Förhandsversioner

En API-version med etiketten "prerelease" anger att versionen inte är redo för produktion, och den bör endast användas i testmiljöer. Dessa slutpunkter kan uppleva icke-bakåtkompatibla ändringar utan föregående meddelande.

Hur versioner ökas

För närvarande ökar vi bara huvudversionen när det sker en icke-bakåtkompatibel ändring som anses vara bakåtkompatibel.

Här följer några exempel på icke-bakåtkompatibla ändringar (huvudversionen ökas):

Byta namn på eller ta bort slutpunkter.
Ta bort parametrar eller lägga till obligatoriska parametrar.
Ändra statuskod.
Ta bort en egenskap i ett svar eller ändra en svarstyp alls. Det är okej att lägga till egenskaper i svaret.
Ändra typ av egenskap.
Beteende när ett API ändras, till exempel ändringar i affärslogik som används för att göra foo, men det hindrar nu.

Icke-bakåtkompatibla ändringar (versionen är inte inkrementerad):

Tillägg av egenskaper som är nullbara eller har ett standardvärde.
Tillägg av egenskaper till en svarsmodell.
Ändra ordningen på egenskaper.

Rubrik som svar

ReportApiVersions är aktiverat, vilket innebär att systemet returnerar rubrikerna api-supported-versions och api-deprecated-versions när det är lämpligt.

api-supported-versions listar vilka versioner som stöds för det begärda API:et. Den returneras bara när du anropar en slutpunkt som har kommenterats med ApiVersion("<someVersion>").
api-deprecated-versions listar vilka versioner som har blivit inaktuella för det begärda API:et. Den returneras bara när du anropar en slutpunkt som har kommenterats med ApiVersion("<someVersion>", Deprecated = true).

Exempel:

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

Kommentar

DICOM® är ett registrerat varumärke som tillhör National Electrical Manufacturers Association för dess standarder publikationer som rör digital kommunikation av medicinsk information.

Dela via