APIs abertas são um meio chave para equipes técnicas fornecerem serviços e dados a usuários externos. À medida que os negócios se desenvolvem e a tecnologia evolui, as APIs exigem iterações regulares de versão. Essas iterações normalmente visam atender às demandas do mercado, otimizar funcionalidades existentes, adicionar novos recursos ou corrigir vulnerabilidades.
Com várias versões coexistindo, as equipes precisam garantir que cada versão atenda a diferentes necessidades dos usuários. Alguns usuários podem exigir a versão mais recente da API para acessar os recursos mais novos, enquanto outros podem contar com a estabilidade de versões mais antigas.
Na prática, as equipes podem precisar fornecer várias versões da API para usuários externos, como a versão mais recente, versão estável ou versão de suporte a longo prazo. Essa abordagem garante compatibilidade e estabilidade para diferentes grupos de usuários, minimizando o impacto das atualizações nos usuários de API mais antigos.
Com base em tais cenários, a Apidog oferece um recurso prático de "Versão de API". Isso permite que as equipes criem, gerenciem e mantenham diferentes versões de API com facilidade, garantindo que cada versão opere de forma independente e seja claramente diferenciada das outras.
Usando o Recurso de Versão de API na Apidog
Passo 1: Criando uma Versão de API
Após acessar seu projeto, clique no seletor de ramificações acima do diretório do projeto e selecione "Conteúdo da Versão" para visualizar todas as versões de API no projeto atual. Clique em "Nova Versão de API", nomeie-a e escolha o conteúdo inicial.
Depois de salvar, o sistema mudará automaticamente para a nova versão, permitindo que você edite recursos dentro dessa versão independentemente, sem afetar a versão original.
Passo 2: Publicando Versões de API na Documentação
Uma vez que uma versão de API é criada, você pode ir para a página "Compartilhar Documentos -> Configurações de Publicação" no projeto para selecionar a versão de API que deseja publicar.
Depois de definir as opções de publicação, a versão de API selecionada será exibida no endereço público do projeto, tornando-a acessível aos usuários externos.
Clique no botão "Editar" para escolher a versão da API para publicação. Você pode definir a origem da versão, exibir números de versão, ambientes de execução e Slug.
https://example.Apidog.cn/2-0-0, 2-0-0 é o Slug, permitindo que usuários externos acessem diretamente essa versão específica da API. Isso garante que cada versão da API tenha um caminho de acesso único e claro.Você também pode ajustar a ordem das versões publicadas. A versão listada primeiro se tornará a versão padrão, que os usuários verão ao acessar o endereço do projeto sem especificar uma versão.
Após concluir as configurações, clique em "Publicar", e o status do projeto inteiro mudará para "Publicar". Os usuários externos poderão então acessar a documentação através do endereço do projeto da Apidog para visualizar e alternar entre diferentes versões da API.
Passo 3: Compartilhamento Rápido de Interfaces em Versões de API
Além de divulgar versões de API, você também pode compartilhar rapidamente interfaces específicas de qualquer versão da API.
Ao criar um link de compartilhamento, selecione a versão da API e o intervalo de interfaces que deseja compartilhar.
Após gerar o link de compartilhamento, os usuários externos poderão visualizar as interfaces que você especificou naquela versão da API.
Passo 4: Deletando Versões de API
Você pode deletar uma versão de API já criada em "Configurações do Projeto -> Versões de API" na ramificação principal.
Após a exclusão, a documentação publicamente publicada não incluirá mais essa versão, e quaisquer links de compartilhamento associados se tornarão inválidos, impedindo os usuários de acessar o conteúdo da versão deletada por meio desses links.
Perguntas Frequentes sobre Versionamento de API
Qual é a diferença entre versões de API e ramificações de sprint?
Versões de API: Principalmente usadas para publicação externa. Recomenda-se criar uma nova versão quando ocorrências significativas que sejam incompatíveis com a versão antiga acontecerem. As versões de API contêm um conjunto completo de interfaces.
Ramificações de Sprint: Principalmente usadas para iterações de desenvolvimento em equipe. Uma ramificação é criada para cada iteração e depois mesclada na ramificação principal após a conclusão. As ramificações de sprint geralmente contêm apenas as interfaces novas e modificadas da iteração atual.
O recurso de versão da API suporta todos os tipos de interfaces?
Atualmente, o recurso suporta apenas interfaces HTTP.
Quem pode criar e modificar versões de API?
Administradores de projeto e editores de projeto podem criar e modificar versões de API.
Quem pode publicar ou deletar versões de API?
Apenas administradores de projeto podem publicar ou deletar versões de API.
Mudanças nos recursos associados afetarão a versão da API?
Não. Os recursos dentro de cada versão de API são independentes.
Existem planos para suportar mais recursos, como suporte multilíngue?
Sim, estamos desenvolvendo ativamente recursos como suporte multilíngue e pulls entre ramificações/versionamento. Esses recursos serão lançados em versões futuras para melhorar ainda mais a eficiência de gerenciamento da documentação da API e atender a mais necessidades dos usuários.
E quanto a melhorias para ramificações de sprint?
Atualizações nas capacidades da ramificação de sprint estão em andamento, com planos para suportar recursos como copiando recursos de outras ramificações, selecionando recursos de outras ramificações, revisões de mesclagem de ramificações e bloqueio de ramificações nas próximas atualizações.
Conclusão
Com o recurso de versão da API fornecido pela Apidog, as equipes podem criar e gerenciar eficientemente múltiplas versões de API, garantindo estabilidade para versões mais antigas enquanto introduzem novos recursos.