Partilhar via

Controlo de versões de API do serviço DICOM

  • Artigo

Este guia de referência fornece uma visão geral das políticas de versão da API para o serviço DICOM®.

Especificando a versão da API REST em solicitações

A versão da API REST deve ser especificada explicitamente na URL da solicitação, como no exemplo a seguir:

<service_url>/v<version>/studies

Não há suporte para rotas sem uma versão.

Versões suportadas

Atualmente, as versões suportadas são:

  • v1.0-pré-lançamento
  • v1
  • v2

O OpenAPI Doc para as versões suportadas pode ser encontrado no seguinte url:

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

Declaração de conformidade DICOM

Todas as versões das APIs DICOM estão em conformidade com as especificações DICOMweb™ Standard, mas versões diferentes podem expor APIs diferentes. Consulte a versão específica da declaração de conformidade para obter detalhes:

Versões de pré-lançamento

Uma versão da API com o rótulo "pré-lançamento" indica que a versão não está pronta para produção e só deve ser usada em ambientes de teste. Esses pontos de extremidade podem sofrer alterações de quebra sem aviso prévio.

Como as versões são incrementadas

Atualmente, só incrementamos a versão principal sempre que há uma alteração de quebra, que é considerada não compatível com versões anteriores.

Aqui estão alguns exemplos de alterações de quebra (a versão principal é incrementada):

  • Renomeando ou removendo pontos de extremidade.
  • Remoção de parâmetros ou adição de parâmetros obrigatórios.
  • Alterar o código de estado.
  • Excluir uma propriedade em uma resposta ou alterar um tipo de resposta. Não há problema em adicionar propriedades à resposta.
  • Alterar o tipo de uma propriedade.
  • Comportamento quando uma API muda, como alterações na lógica de negócios costumava fazer foo, mas agora não barra.

Alterações ininterruptas (a versão não é incrementada):

  • Adição de propriedades que são anuláveis ou têm um valor padrão.
  • Adição de propriedades a um modelo de resposta.
  • Alterar a ordem das propriedades.

Cabeçalho em resposta

ReportApiVersions está ativado, o que significa que o sistema retorna os cabeçalhos api-supported-versions e api-deprecated-versions quando apropriado.

  • api-supported-versions lista quais versões são suportadas para a API solicitada. Ele só é retornado ao chamar um ponto de extremidade anotado com ApiVersion("<someVersion>").

  • api-deprecated-versions lista quais versões foram preteridas para a API solicitada. Ele só é retornado ao chamar um ponto de extremidade anotado com ApiVersion("<someVersion>", Deprecated = true).

Exemplo:

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

Captura de ecrã das versões suportadas e preteridas da API.

Nota

DICOM® é a marca registrada da National Electrical Manufacturers Association para suas publicações de padrões relacionados a comunicações digitais de informações médicas.