Controlo de versões de API do serviço DICOM
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)]
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