Control de versiones de API para el servicio DICOM

  • Artículo

En esta guía de referencia se proporciona información general sobre las directivas de versión de API para el servicio DICOM.

Especificación de la versión de la API REST en las solicitudes

La versión de la API REST debe especificarse explícitamente en la dirección URL de la solicitud como en el ejemplo siguiente:

<service_url>/v<version>/studies

Nota:

No se admiten rutas sin una versión.

Versiones compatibles

Actualmente, las versiones compatibles son las siguientes:

  • v1.0-prerelease
  • v1
  • v2

La documentación de OpenAPI para las versiones admitidas se puede encontrar en la siguiente dirección URL:

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

Declaración de conformidad de DICOM

Todas las versiones de las API diCOM siempre se ajustan a las especificaciones estándar de DICOMweb™, pero las distintas versiones pueden exponer diferentes API. Consulte la versión específica de la instrucción de conformidad para obtener más información:

Versiones preliminares

Una versión de API con la etiqueta "versión preliminar" indica que la versión no está lista para producción y que solo debe usarse en entornos de prueba. Estos puntos de conexión pueden experimentar cambios importantes sin previo aviso.

Cómo se incrementan las versiones

Actualmente solo se incrementa la versión principal cada vez que se produce un cambio importante, que se considera que no es compatible con versiones anteriores.

A continuación se muestran algunos ejemplos de cambios importantes (se incrementa la versión principal):

  • Cambio de nombre o eliminación de puntos de conexión.
  • Eliminación de parámetros o adición de parámetros obligatorios.
  • Cambio del código de estado.
  • Eliminación de una propiedad en una respuesta o modificación de un tipo de respuesta, pero se permite agregar propiedades a la respuesta.
  • Cambio del tipo de una propiedad.
  • El comportamiento cuando cambia una API, como los cambios en la lógica de negocios, en la que antes se usaba foo, pero ahora se utiliza bar.

Cambios no importantes (la versión no se incrementa):

  • Adición de propiedades que admiten un valor NULL o tienen un valor predeterminado.
  • Adición de propiedades a un modelo de respuesta.
  • Cambio del orden de las propiedades.

Encabezado en respuesta

ReportApiVersions está activado, lo que significa que devolveremos los encabezados api-supported-versions y api-deprecated-versions cuando corresponda.

  • api-supported-versions mostrará las versiones que se admiten para la API solicitada. Solo se devuelve cuando se llama a un punto de conexión anotado con ApiVersion("<someVersion>").

  • api-deprecated-versions mostrará las versiones que han quedado en desuso para la API solicitada. Solo se devuelve cuando se llama a un punto de conexión anotado con ApiVersion("<someVersion>", Deprecated = true).

Ejemplo:

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

Captura de pantalla de las versiones admitidas y en desuso de la API.

Pasos siguientes

En este artículo, ha obtenido información sobre las directivas de versión de API para el servicio DICOM. Para obtener más información sobre el servicio DICOM, consulte

Introducción al servicio DICOM