Esta página se aplica à Apigee e à Apigee híbrida.
Neste tópico, explicamos o que você precisa saber sobre como criar e gerenciar versões no Hub de API.
O que é uma versão?
Cada recurso de API no hub de API tem pelo menos uma versão associada a ele. A versão pode ser considerada o estado de uma API em um determinado momento. Basicamente, as versões ajudam você a agrupar e organizar suas APIs com base em conjuntos subjacentes de operações, implantações, especificações e outros atributos, conforme mostrado na Figura 1.
Figura 1. Cada versão pode ter operações, implantações e outros atributos.
No hub de API, uma versão representa um agrupamento lógico de APIs. Geralmente, mas não necessariamente, esse agrupamento gira em torno das operações que uma API pode realizar. Por exemplo, digamos que você tenha uma API Pet Store e a primeira versão dela permita realizar tarefas básicas, como adicionar um animal de estimação, encontrar e excluir um da loja. Estes são exemplos de operações.
A prática recomendada é que uma versão inclua um conjunto de operações de API implantadas juntas. Por exemplo, uma API Pet Store pode ter uma versão que inclui operações de adição, localização e exclusão, todas implantadas nos mesmos ambientes.
Outra boa maneira de pensar em uma versão é que ela representa a visão do produtor da API. É o conjunto de recursos e capacidades que as pessoas que a criaram colocam nela e esperam ser implantados com ela.
Criar versões
Suponha que os detalhes de uma API que você quer adicionar ao hub de API sejam capturados em uma especificação OpenAPI. Nesse caso, você pode adicionar a especificação a uma versão da API. Quando você faz isso, o hub da API analisa a especificação e extrai informações dela, como quais operações a API inclui, e armazena essas informações com a versão. Se você não tiver uma especificação OpenAPI, ainda poderá criar uma versão, mas precisará preenchê-la manualmente com informações descritivas relevantes. Outro caso em que o hub de APIs permite a análise de detalhes da API pelo registro automático de proxies de API da Apigee.
Você pode fazer upload de vários arquivos de especificação de API para a mesma versão.
Quando criar uma nova versão?
Se novas operações forem adicionadas a uma API, talvez ela justifique a criação de uma nova versão, ou não.
Digamos que o produtor da API adicione uma nova operação a uma API e pretenda implantá-la em todas as implantações atualmente associadas à versão. Nesse caso, o produtor pode optar por não criar uma nova versão da API. Por outro lado, se o produtor fizer uma alteração incompatível com versões anteriores (uma alteração interruptiva) e optar por associá-la a uma nova implantação, talvez você queira criar uma nova versão.
O hub de API oferece flexibilidade para definir e organizar as versões da API de acordo com as necessidades da sua organização e de produtores de API específicos.
Atributos do sistema
Por padrão, as versões incluem os seguintes atributos do sistema. É possível modificar os valores associados a esses atributos em Configurações. Para detalhes, consulte Gerenciar atributos.
| Atributo | Descrição |
|---|---|
| Lifecycle | O ciclo de vida se refere a um conjunto ordenado de estágios pelas quais uma API deve progredir, da concepção ao fim da vida útil. Como cada versão de uma API geralmente passa pelo próprio ciclo de vida separadamente, não configuramos diretamente o estágio de ciclo de vida de uma API. Em vez disso, permitimos que cada versão da API tenha um estágio de ciclo de vida atribuído. |
| Compliance | Em Configurações, é possível definir valores que representem os detalhes de conformidade de interesse da sua equipe ou organização. Para detalhes, consulte Gerenciar atributos. |
| Credenciamento | Em Configurações, é possível definir valores que representem os detalhes de credenciamento de interesse da sua equipe ou organização. Para detalhes, consulte Gerenciar atributos. |
| Documentação | Um link para a documentação da API à qual a versão está anexada. |
Atributos definidos pelo usuário
Dependendo das necessidades da sua equipe ou organização, é possível definir atributos personalizados (pares de nome/valor) para as versões. Consulte Gerenciar atributos.