API-Versionsverwaltung für den DICOM-Dienst
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)]
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