API-versiebeheer voor de DICOM-service
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