Compartir vía

Control de versiones de API para el servicio DICOM

  • Artículo

Esta guía de referencia 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

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 de DICOM se ajustan a las especificaciones de DICOMweb™ Standard, pero las distintas versiones pueden exponer distintas 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.

Estos son 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.
  • Eliminar una propiedad en una respuesta o modificar un tipo de respuesta en absoluto. Está bien 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 sin interrupción (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 el sistema devuelve los encabezados api-supported-versions y api-deprecated-versions cuando corresponda.

  • api-supported-versions enumera qué versiones son compatibles con la API solicitada. Solo se devuelve cuando se llama a un punto de conexión anotado con ApiVersion("<someVersion>").

  • api-deprecated-versions enumera qué versiones 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.

Nota:

DICOM® es la marca registrada de la Asociación Nacional de Fabricantes Eléctricos para sus publicaciones de normas relacionadas con las comunicaciones digitales de información médica.