API-versiebeheer voor de DICOM-service

Artikel
04/28/2023

Deze naslaghandleiding biedt een overzicht van het API-versiebeleid voor de DICOM-service.

Versie van REST API opgeven in aanvragen

De versie van de REST API moet expliciet worden opgegeven in de aanvraag-URL, zoals in het volgende voorbeeld:

<service_url>/v<version>/studies

Notitie

Routes zonder versie worden niet ondersteund.

Ondersteunde versies

Momenteel zijn de ondersteunde versies:

v1.0-prerelease
v1
v2

Het OpenAPI-document voor de ondersteunde versies vindt u op de volgende URL:

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

DICOM-conformiteitsverklaring

Alle versies van de DICOM API's voldoen altijd aan de DICOMweb™ Standard-specificaties, maar verschillende versies kunnen verschillende API's beschikbaar maken. Zie de specifieke versie van de conformiteitsverklaring voor meer informatie:

Voorlopige versies

Een API-versie met het label 'prerelease' geeft aan dat de versie niet gereed is voor productie en alleen moet worden gebruikt in testomgevingen. Deze eindpunten kunnen zonder kennisgeving te maken hebben met wijzigingen die fouten veroorzaken.

Hoe versies worden verhoogd

Momenteel wordt de primaire versie alleen verhoogd wanneer er een wijziging is die fouten veroorzaakt. Deze wordt beschouwd als niet compatibel met eerdere versies.

Hieronder vindt u enkele voorbeelden van wijzigingen die fouten veroorzaken (primaire versie wordt verhoogd):

De naam van eindpunten wijzigen of verwijderen.
Parameters verwijderen of verplichte parameters toevoegen.
Statuscode wijzigen.
Een eigenschap in een antwoord verwijderen of een antwoordtype helemaal wijzigen, maar het is geen probleem om eigenschappen toe te voegen aan het antwoord.
Het type van een eigenschap wijzigen.
Gedrag wanneer een API wordt gewijzigd, zoals wijzigingen in bedrijfslogica die voorheen werd gebruikt om foo uit te voeren, maar dit nu wel het geval is.

Wijzigingen die fouten veroorzaken (versie wordt niet verhoogd):

Toevoeging van eigenschappen die null zijn of een standaardwaarde hebben.
Toevoeging van eigenschappen aan een antwoordmodel.
De volgorde van eigenschappen wijzigen.

Header in antwoord

ReportApiVersions is ingeschakeld, wat betekent dat we de headers api-supported-versions en api-deprecated-versions retourneren, indien van toepassing.

api-supported-versions vermeldt welke versies worden ondersteund voor de aangevraagde API. Deze wordt alleen geretourneerd bij het aanroepen van een eindpunt met aantekeningen.ApiVersion("<someVersion>")
api-deprecated-versions vermeldt welke versies zijn afgeschaft voor de aangevraagde API. Deze wordt alleen geretourneerd bij het aanroepen van een eindpunt met aantekeningen.ApiVersion("<someVersion>", Deprecated = true)

Voorbeeld:

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

Volgende stappen

In dit artikel hebt u geleerd over het API-versiebeleid voor de DICOM-service. Zie voor meer informatie over de DICOM-service

Overzicht van de DICOM-service

Delen via