Delen via

API-versiebeheer voor de DICOM-service

  • Artikel

Deze referentiehandleiding 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

Routes zonder versie worden niet ondersteund.

Ondersteunde versies

Momenteel zijn de ondersteunde versies:

  • v1.0-prerelease
  • v1
  • v2

De OpenAPI-documentatie voor de ondersteunde versies vindt u op de volgende URL:

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

DICOM Conformance-instructie

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

Prereleaseversies

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

Hoe versies worden verhoogd

We verhogen momenteel alleen de primaire versie wanneer er een belangrijke wijziging is, die wordt beschouwd als niet compatibel met eerdere versies.

Hier volgen enkele voorbeelden van belangrijke wijzigingen (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 wijzigen. 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 worden gebruikt om foo uit te voeren, maar nu wel balk.

Niet-vaste wijzigingen (versie wordt niet verhoogd):

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

Koptekst in antwoord

ReportApiVersions is ingeschakeld, wat betekent dat het systeem de headers api-ondersteunde versies en api-afgeschafte versies retourneert, indien van toepassing.

  • api-ondersteunde versies vermeldt welke versies worden ondersteund voor de aangevraagde API. Het wordt alleen geretourneerd bij het aanroepen van een eindpunt met aantekeningen.ApiVersion("<someVersion>")

  • api-afgeschafte versies vermeldt welke versies zijn afgeschaft voor de aangevraagde API. Het wordt alleen geretourneerd bij het aanroepen van een eindpunt met aantekeningen.ApiVersion("<someVersion>", Deprecated = true)

Voorbeeld:

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

Schermopname van de ondersteunde en afgeschafte API-versies.

Notitie

DICOM® is het gedeponeerde handelsmerk van de National Electrical Manufacturers Association voor haar standaardenpublicaties met betrekking tot digitale communicatie van medische informatie.