Controle de versão da API para o serviço DICOM

Artigo
11/09/2024

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 documento OpenAPI para as versões suportadas pode ser encontrado no seguinte url:

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

Instrução de compatibilidade com DICOM

Todas as versões das APIs DICOM estão em conformidade com as especificações do padrão DICOMweb™, 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 endpoints podem sofrer alterações significativas sem aviso prévio.

Como as versões são incrementadas

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

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

Renomear ou remover pontos de extremidade.
Removendo parâmetros ou adicionando parâmetros obrigatórios.
Alterando o código de status.
Excluir uma propriedade em uma resposta ou alterar um tipo de resposta. Não há problema em adicionar propriedades à resposta.
Alterando o tipo de uma propriedade.
Comportamento quando uma API muda, como mudanças na lógica de negócios costumava fazer foo, mas agora faz bar.

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 padrão.
Adição de propriedades a um modelo de resposta.
Alterando 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 compatíveis com a API solicitada. Ele só é retornado ao chamar um ponto de extremidade anotado com ApiVersion("<someVersion>").
api-deprecated-versions lista quais versões foram descontinuadas 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)]

Observação

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

Compartilhar via