Gestion des versions d’API pour le service DICOM
Ce guide de référence vous fournit une vue d’ensemble des stratégies de version de l’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 la demande, comme dans l’exemple suivant :
<service_url>/v<version>/studies
Notes
Les itinéraires sans version ne sont pas pris en charge.
Versions prises en charge
Actuellement, les versions prises en charge sont les suivantes :
- préversion v1.0
- v1
- v2
Le document OpenAPI pour les versions prises en charge se trouve à l’URL suivante :
<service_url>/v<version>/api.yaml
Instruction de conformité DICOM
Toutes les versions des API DICOM seront toujours conformes aux spécifications de DICOMweb™ Standard, mais différentes versions peuvent exposer des API différentes. Pour plus d’informations, consultez la version spécifique de l’instruction de conformité :
Versions préliminaires
Une version d’API avec l’étiquette « prérelease » 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 subir des modifications cassants sans préavis.
Incrémentation des versions
Actuellement, nous incrémentons la version principale uniquement chaque fois qu’il y a un changement cassant, qui est considéré comme non rétrocompatible.
Voici quelques exemples de modifications cassants (la version principale est incrémentée) :
- Renommage ou suppression des points de terminaison.
- Suppression de paramètres ou ajout de paramètres obligatoires.
- Modification du code status.
- Suppression d’une propriété dans une réponse ou modification d’un type de réponse, mais 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 effectuer des opérations de foo, mais elle ne l’est désormais pas.
Modifications non cassants (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 nous retournerons 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. Il est retourné 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épréciées pour l’API demandée. Il est retourné 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)]
Étapes suivantes
Dans cet article, vous avez découvert les stratégies de version de l’API pour le service DICOM. Pour plus d’informations sur le service DICOM, consultez