Freigeben über

API-Versionsverwaltung für den DICOM-Dienst

  • Artikel

In diesem Referenzhandbuch finden Sie eine Übersicht über die API-Versionsrichtlinien für den DICOM-Dienst®.

Angeben der Version der REST-API in Anforderungen

Die Version der REST-API muss explizit in der Anforderungs-URL angegeben werden, wie im folgenden Beispiel gezeigt:

<service_url>/v<version>/studies

Routen ohne Version werden nicht unterstützt.

Unterstützte Versionen

Derzeit sind die unterstützten Versionen:

  • v1.0-prerelease
  • v1
  • V2

Das OpenAPI-Dokument für die unterstützten Versionen finden Sie unter der folgenden URL:

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

DICOM-Konformitätserklärung

Alle Versionen der DICOM-APIs entsprechen den DICOMweb-Standardspezifikationen™, aber unterschiedliche Versionen können unterschiedliche APIs verfügbar machen. Details finden Sie in der spezifischen Version der Konformitätserklärung:

Vorabversionen

Eine API-Version mit der Bezeichnung "Vorabversion" gibt an, dass die Version nicht für die Produktion bereit ist und nur in Testumgebungen verwendet werden sollte. Diese Endpunkte können zu unterbrechungsfreier Änderung führen.

Wie Versionen erhöht werden

Wir erhöhen derzeit nur die Hauptversion, wenn es eine grundlegende Änderung gibt, die als nicht abwärtskompatibel gilt.

Hier sind einige Beispiele für grundlegende Änderungen (Hauptversion ist inkrementiert):

  • Umbenennen oder Entfernen von Endpunkten.
  • Entfernen von Parametern oder Hinzufügen obligatorischer Parameter.
  • Statuscode wird geändert.
  • Löschen einer Eigenschaft in einer Antwort oder Ändern eines Antworttyps überhaupt. Es ist in Ordnung, der Antwort Eigenschaften hinzuzufügen.
  • Ändern des Typs einer Eigenschaft.
  • Verhalten, wenn sich eine API ändert, z. B. Änderungen in der Geschäftslogik, die zum Ausführen von Foo verwendet werden, aber jetzt Balken.

Geschützte Änderungen (Version wird nicht erhöht):

  • Hinzufügen von Eigenschaften, die nullfähig sind oder einen Standardwert aufweisen.
  • Hinzufügen von Eigenschaften zu einem Antwortmodell.
  • Ändern der Reihenfolge der Eigenschaften.

Kopfzeile in Antwort

ReportApiVersions ist aktiviert, was bedeutet, dass das System bei Bedarf die Header api-supported-versions und api-deprecated-versions zurückgibt.

  • Api-supported-versions listet auf, welche Versionen für die angeforderte API unterstützt werden. Er wird nur zurückgegeben, wenn ein Endpunkt mit Anmerkungen versehen wird ApiVersion("<someVersion>").

  • Api-veraltete Versionen listen auf, welche Versionen für die angeforderte API veraltet sind. Er wird nur zurückgegeben, wenn ein Endpunkt mit Anmerkungen versehen wird ApiVersion("<someVersion>", Deprecated = true).

Beispiel:

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

Screenshot der unterstützten und veralteten VERSIONEN der API.

Hinweis

DICOM® ist die eingetragene Marke des National Electrical Manufacturers Association für seine Standards-Publikationen über die digitale Kommunikation medizinischer Informationen.