Gestion des versions d’API pour le service DICOM

Article
11/09/2024

Ce guide de référence vous fournit une vue d’ensemble des stratégies de version d’API pour le service DICOM®.

Spécification de la version de l’API REST dans les requêtes

La version de l’API REST doit être spécifiée explicitement dans l’URL de requête, comme dans l’exemple suivant :

<service_url>/v<version>/studies

Les itinéraires sans version ne sont pas pris en charge.

Versions prises en charge

Actuellement, les versions prises en charge sont les suivantes :

v1.0-prerelease
v1
v2

La documentation OpenAPI pour les versions prises en charge se trouve à l’URL suivante :

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

Déclaration de conformité de DICOM

Toutes les versions des API DICOM sont conformes aux spécifications DICOMweb™ Standard, mais différentes versions peuvent exposer différentes API. Pour plus d’informations, consultez la version spécifique de l’instruction de conformité :

Préversions

Une version d’API avec l’étiquette « préversion » indique que la version n’est pas prête pour la production et qu’elle ne doit être utilisée que dans les environnements de test. Ces points de terminaison peuvent rencontrer des changements cassants sans préavis.

Comment les versions sont incrémentées

Actuellement, nous incrémentons uniquement la version principale chaque fois qu’il y a une modification cassant, qui est considérée comme non compatible descendante.

Voici quelques exemples de changements cassants (la version principale est incrémentée) :

Renommage ou suppression de points de terminaison.
Suppression de paramètres ou ajout de paramètres obligatoires.
Modification du code d’état.
Suppression d’une propriété dans une réponse ou modification d’un type de réponse du tout. Il est possible d’ajouter des propriétés à la réponse.
Modification du type d’une propriété.
Comportement lorsqu’une API change, comme les modifications de la logique métier utilisée pour faire foo, mais elle fait désormais barre.

Modifications non cassantes (la version n’est pas incrémentée) :

Ajout de propriétés nullables ou ayant une valeur par défaut.
Ajout de propriétés à un modèle de réponse.
Modification de l’ordre des propriétés.

En-tête en réponse

ReportApiVersions est activé, ce qui signifie que le système retourne les en-têtes api-supported-versions et api-deprecated-versions le cas échéant.

api-supported-versions répertorie les versions prises en charge pour l’API demandée. Elle est retournée uniquement lors de l’appel d’un point de terminaison annoté avec ApiVersion("<someVersion>").
api-deprecated-versions répertorie les versions qui ont été déconseillées pour l’API demandée. Elle est retournée uniquement lors de l’appel d’un point de terminaison annoté avec ApiVersion("<someVersion>", Deprecated = true).

Exemple :

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

Remarque

DICOM® est une marque déposée de la National Electrical Manufacturers Association pour ses publications de standards relatifs aux communications numériques des informations médicales.

Partager via