API-Versionsverwaltung für den DICOM-Dienst

  • Artikel

In diesem Referenzhandbuch erhalten 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

Hinweis

Routen ohne Version werden nicht unterstützt.

Unterstützte Versionen

Derzeit werden folgende Versionen unterstützt:

  • v1.0-Vorabversion
  • 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 immer den DICOMweb™ Standard-Spezifikationen, aber unterschiedliche Versionen können unterschiedliche APIs verfügbar machen. Weitere Informationen 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 ohne Vorheriges zu Breaking Changes führen.

Inkrementierung von Versionen

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

Im Folgenden finden Sie einige Beispiele für breaking changes (Hauptversion wird erhöht):

  • Umbenennen oder Entfernen von Endpunkten.
  • Entfernen von Parametern oder Hinzufügen obligatorischer Parameter.
  • Ändern von status Code.
  • Löschen einer Eigenschaft in einer Antwort oder Ändern eines Antworttyps überhaupt, aber 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 für foo verwendet werden, aber sie führt jetzt bar aus.

Nicht breaking changes (Version isn't inkrmented):

  • Hinzufügen von Eigenschaften, die NULL-Werte zulassen oder einen Standardwert aufweisen.
  • Hinzufügen von Eigenschaften zu einem Antwortmodell.
  • Ändern der Reihenfolge der Eigenschaften.

Header als Antwort

ReportApiVersions ist aktiviert. Dies bedeutet, dass die Header api-supported-versions und api-deprecated-versions bei Bedarf zurückgegeben werden.

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

  • api-deprecated-versions listet auf, welche Versionen für die angeforderte API veraltet sind. Sie wird nur zurückgegeben, wenn ein Endpunkt mit ApiVersion("<someVersion>", Deprecated = true)Anmerkungen aufgerufen wird.

Beispiel:

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

Screenshot der unterstützten und veralteten Versionen der API.

Nächste Schritte

In diesem Artikel haben Sie die API-Versionsrichtlinien für den DICOM-Dienst kennengelernt. Weitere Informationen zum DICOM-Dienst finden Sie unter

Übersicht über den DICOM-Dienst