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

  • Artigo

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

Especificar a versão da API REST nos pedidos

A versão da API REST tem de ser especificada explicitamente no URL do pedido, tal como no exemplo seguinte:

<service_url>/v<version>/studies

Nota

As rotas sem uma versão não são suportadas.

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 estarão sempre em conformidade com as especificações padrão DICOMweb™, mas versões diferentes podem expor APIs diferentes. Veja a versão específica da instrução de conformidade para obter detalhes:

Versões de pré-lançamento

Uma versão da API com a etiqueta "pré-lançamento" indica que a versão não está pronta para produção e que só deve ser utilizada em ambientes de teste. Estes pontos finais podem sofrer alterações interruptivas sem aviso prévio.

Como as versões são incrementadas

Atualmente, só incrementamos a versão principal sempre que ocorrer uma alteração interruptiva, que é considerada não retrocompatível.

Seguem-se alguns exemplos de alterações interruptivas (a versão principal é incrementada):

  • Mudar o nome ou remover pontos finais.
  • Remover parâmetros ou adicionar parâmetros obrigatórios.
  • Alterar o código de estado.
  • Eliminar uma propriedade numa resposta ou alterar um tipo de resposta, mas não há problema em adicionar propriedades à resposta.
  • Alterar o tipo de uma propriedade.
  • Comportamento quando uma API é alterada, como alterações na lógica de negócio utilizadas para fazer foo, mas agora faz barra.

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

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

Cabeçalho na resposta

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

  • as versões suportadas por API irão listar as versões suportadas para a API pedida. Só é devolvido ao chamar um ponto final anotado com ApiVersion("<someVersion>").

  • api-deprecated-versions irá listar as versões que foram preteridas para a API pedida. Só é devolvido ao chamar um ponto final anotado com ApiVersion("<someVersion>", Deprecated = true).

Exemplo:

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

Captura de ecrã a mostrar as versões suportadas e preteridas da API.

Passos seguintes

Neste artigo, ficou a conhecer as políticas de versão da API para o serviço DICOM. Para obter mais informações sobre o serviço DICOM, consulte

Descrição geral do serviço DICOM