Versões no Gerenciamento de API do Azure

APLICA-SE A: Todas as camadas de gerenciamento de API

As versões permitem que você apresente grupos de APIs relacionadas aos seus desenvolvedores. Pode utilizar versões para lidar com alterações interruptivas na sua API em segurança. Os clientes podem optar por utilizar a sua nova versão da API quando estiverem prontos, enquanto os clientes existentes continuam a utilizar uma versão mais antiga. As versões são diferenciadas por meio de um identificador de versão (que é qualquer valor de cadeia de caracteres escolhido) e um esquema de controle de versão permite que os clientes identifiquem qual versão de uma API desejam usar. Este artigo descreve como usar versões no Gerenciamento de API.

Para a maioria das finalidades, cada versão da API pode ser considerada a sua própria API independente. Duas versões da API diferentes podem ter diferentes conjuntos de operações e políticas diferentes.

Com as versões, pode:

• Publique várias versões da sua API ao mesmo tempo.
• Use um caminho, cadeia de caracteres de consulta ou cabeçalho para diferenciar entre versões.
• Use qualquer valor de cadeia de caracteres que deseje para identificar a sua versão. Pode ser um número, uma data ou um nome.
• Mostre suas versões de API agrupadas no portal do desenvolvedor.
• Crie uma nova versão de uma API existente (sem versão) sem afetar os clientes existentes.

Comece a trabalhar com versões, seguindo um guia passo a passo.

Esquemas de controle de versão

Diferentes desenvolvedores de API têm requisitos diferentes para controle de versão. O Gerenciamento de API do Azure não prescreve uma única abordagem para o controle de versão, mas fornece várias opções.

Controle de versão baseado em caminho

Quando o esquema de controle de versão de caminho é usado, o identificador de versão precisa ser incluído no caminho da URL para todas as solicitações de API.

Por exemplo, https://apis.contoso.com/products/v1 e https://apis.contoso.com/products/v2 poderiam referir-se à mesma products API, mas a versões v1 e v2.

O formato de uma URL de solicitação de API quando você usa o controle de versão baseado em caminho é https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Controle de versão baseado em cabeçalho

Quando o esquema de controle de versão de cabeçalho é usado, o identificador de versão precisa ser incluído em um cabeçalho de solicitação HTTP para quaisquer solicitações de API. Você pode especificar o nome do cabeçalho da solicitação HTTP.

Por exemplo, você pode criar um cabeçalho personalizado chamado Api-Version, e os clientes podem especificar v1 ou v2 no valor desse cabeçalho.

Controle de versão baseado em cadeia de caracteres de consulta

Quando o esquema de controle de versão da cadeia de caracteres de consulta é usado, o identificador de versão precisa ser incluído em um parâmetro de cadeia de caracteres de consulta para quaisquer solicitações de API. Você pode especificar o nome do parâmetro de cadeia de caracteres de consulta.

O formato de uma URL de solicitação de API quando você usa o controle de versão baseado em cadeia de caracteres de consulta é https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

Por exemplo, https://apis.contoso.com/products?api-version=v1 e https://apis.contoso.com/products?api-version=v2 poderiam referir-se à mesma products API, mas a versões v1 e v2.

Observação

Os parâmetros de consulta não são permitidos na propriedade servers de uma especificação OpenAPI. Se você exportar uma especificação OpenAPI de uma versão da API, uma cadeia de caracteres de consulta não aparecerá na URL do servidor.

Versões originais

Se você adicionar uma versão a uma API sem versão, uma Original versão será criada automaticamente e responderá na URL padrão, sem um identificador de versão especificado. A versão Original garante que quaisquer chamadores existentes não fiquem afetados pelo processo de adição de uma versão. Caso crie uma nova API com versões ativadas desde o início, nenhuma versão Original será criada.

Como as versões são representadas

O Gerenciamento de API mantém um recurso chamado conjunto de versões, que representa um conjunto de versões para uma única API lógica. Um conjunto de versões contém o nome para exibição da API versionada e o esquema de controle de versão usado para direcionar solicitações para versões especificadas.

Cada versão de uma API é mantida como seu próprio recurso de API e está associada a um conjunto de versões. Um conjunto de versões pode conter APIs com operações ou políticas diferentes. Você pode fazer alterações significativas entre as versões de um conjunto.

O portal do Azure cria conjuntos de versões para você. Você pode modificar o nome e a descrição de um conjunto de versões no portal do Azure.

Um conjunto de versões é automaticamente excluído quando a versão final é excluída.

Você pode exibir e gerenciar conjuntos de versões diretamente usando a CLI do Azure, o Azure PowerShell, os modelos do Gerenciador de Recursos ou a API do Gerenciador de Recursos do Azure.

Observação

Todas as versões em um conjunto de versões têm o mesmo esquema de controle de versão. Ele se baseia no esquema de controle de versão usado quando você adiciona uma versão a uma API pela primeira vez.

Migrando uma API sem versão para uma API com versão

Quando você usa o portal do Azure para habilitar o controle de versão em uma API existente, as seguintes alterações são feitas em seus recursos de Gerenciamento de API:

• Um novo conjunto de versões é criado.
• A versão existente é mantida e configurada como a versão da Original API. A API está vinculada ao conjunto de versões, mas um identificador de versão não precisa ser especificado.
• A nova versão é criada como uma nova API e está vinculada ao conjunto de versões. Um esquema de controle de versão e um identificador devem ser usados para acessar a nova API.

Versões e revisões

Versões e revisões são características distintas. Cada versão pode ter várias revisões, assim como uma API sem versão. Você pode usar revisões sem usar versões, ou o contrário. Normalmente, as versões são usadas para separar versões de API que têm alterações que causam incompatibilidades, e as revisões podem ser usadas para alterações menores e não disruptivas de uma API.

Se você achar que sua revisão tem alterações críticas, ou se quiser transformar formalmente sua revisão em uma versão beta/teste, pode gerar uma versão a partir dela. No portal do Azure, selecione Criar Versão a partir desta Revisão no menu de contexto de revisão (...) na guia Revisões .

Portal do programador

O portal do desenvolvedor lista cada versão de uma API separadamente:

Nos detalhes de uma API, você também pode ver uma lista de todas as versões da API. Uma Original versão é exibida sem um identificador de versão:

Sugestão

Você precisa adicionar versões de API a um produto para torná-las visíveis no portal do desenvolvedor.