Iterar e manter APIs é crucial durante o desenvolvimento de produtos. À medida que os produtos evoluem com novos recursos ou ajustes, as atualizações ou modificações correspondentes da API se tornam necessárias, especialmente em ambientes dinâmicos.
C entretanto, a iteração da API nem sempre é direta. Gerenciar APIs juntamente com atualizações ou modificações de produtos frequentemente apresenta desafios:
- Como iterar e testar APIs de forma eficaz, garantindo a estabilidade das APIs existentes?
- Como gerenciar APIs em várias iterações de desenvolvimento paralelas, prevenindo interferências?
Para abordar esses cenários, Apidog introduz o recurso "Sprint Branch". Essa funcionalidade oferece uma maneira flexível de gerenciar APIs, permitindo que você itere, atualize e desenvolva novos recursos em branches independentes sem afetar a estabilidade das APIs online na branch principal.
O recurso Sprint Branch suporta controle de versão, colaboração paralela e fusão rápida. Cada branch é uma versão independente, evitando interferência, e as alterações dentro de uma branch podem ser rapidamente fundidas de volta na branch principal.
Compreendendo os Casos de Uso do Sprint Branch
O recurso "Sprint Branch" permite que você crie múltiplas branches de desenvolvimento dentro de um projeto para atualizar, iterar e testar APIs em diferentes estágios sem impactar a branch principal (ou seja, a versão estável atual).
Quando Considerar Usar o Sprint Branch:
- Desenvolvimento e Testes de Recursos: Desenvolva e teste novos recursos em uma nova branch Sprint sem afetar a versão estável na branch principal.
- Atualizações e Correções de Bugs: Atualize, revise APIs ou corrija bugs em uma branch dedicada, fundindo-os na branch principal após testes bem-sucedidos.
- Experimentação e Validação: Faça modificações experimentais em APIs, verificando sua eficácia antes de decidir se deve fundi-las na branch principal.
Quando Não Usar Branches Sprint:
- Para atualizações menores da API ou correções simples de bugs, pode ser mais conveniente operar diretamente na branch principal.
- Se seu negócio precisar fornecer várias versões da API para usuários externos, recomenda-se usar o recurso "Versionamento de API" para garantir estabilidade e consistência para usuários externos.
Abaixo está uma breve introdução ao recurso "Sprint Branch". Para instruções de uso mais detalhadas, consulte o módulo Sprint Branch na documentação de ajuda. Antes de começar, certifique-se de que o Apidog está atualizado para a versão mais recente.
Criando uma Sprint Branch
Se o seu papel no projeto é "Admin" ou "Editor", você pode criar uma nova Sprint branch para começar o trabalho relacionado à iteração clicando na opção "Nova Sprint Branch" no componente "Sprint Branch" no canto superior direito da árvore de diretórios.
Desenhando APIs em uma Sprint Branch
O recurso Sprint Branch do Apidog cobre apenas conteúdo modificado ou recém-adicionado durante a iteração. Portanto, a nova Sprint branch está inicialmente vazia, e você precisa selecionar o conteúdo a ser modificado ou adicionado.
Recursos importados, incluindo APIs, casos de uso da API e modelos de dados, terão um identificador de associação claro com a branch principal. Recursos recém-criados dentro da Sprint branch não terão um identificador de associação.
Durante o processo de design da API, você também pode comparar um recurso de Sprint branch específico associado à branch principal para ver as diferenças entre o recurso e a branch principal.
Testando APIs em uma Sprint Branch
A funcionalidade "Testes" também é suportada em branches Sprint. Você pode criar novos "Novos cenários de teste" ou importar existentes da branch principal.
Na árvore de diretórios, os cenários de teste importados terão identificadores de associação claros com recursos na branch principal, semelhante aos identificadores de recursos em "APIs."
Você pode orquestrar cenários de teste em uma Sprint branch exatamente como na branch principal. Como os cenários de teste podem envolver APIs tanto da Sprint branch quanto da branch principal, o sistema utilizará "ícones de branch" para distinguir quais recursos (branch Sprint ou branch principal) são usados em cada etapa de teste.
Quando você clica para visualizar os detalhes dessas etapas, você também pode ver a qual branch pertencem os recursos associados.
Uma vez que as APIs relevantes e os cenários de teste na branch estão desenhados e orquestrados, você pode testá-los.
O sistema usará os dados correspondentes com base na origem do recurso identificada nas etapas para testes automatizados. Se uma etapa de teste é identificada como usando recursos da Sprint branch, o teste usará dados da Sprint branch; se é identificada como usando recursos da branch principal, o teste usará dados da branch principal.
Fundindo uma Sprint Branch
Após completar o desenvolvimento da API e a implantação bem-sucedida na Sprint branch, você pode fundir essas alterações na branch principal. O conteúdo fundido pode ser alterado em algumas ou todas as APIs.
A entrada de fusão está localizada no "Menu Suspenso do Componente de Branch" no canto superior direito da árvore de diretórios. Você também pode ver o botão "Fundir na Branch Principal" abaixo da árvore de diretórios em APIs.
Clicar no botão "Fundir na principal" em APIs abrirá a janela pop-up de visão geral da fusão. Na janela pop-up, você pode visualizar os recursos modificados ou todos os recursos entre a Sprint branch atual e a branch principal. Você também pode escolher como ajustar o status dos recursos na branch principal após a fusão (por exemplo, "Em Desenvolvimento", "Em Teste", "Publicado", etc.).
Clicar em um recurso na árvore de diretórios expandirá para mostrar seu conteúdo detalhado, ajudando você a decidir se deve fundi-lo. Diferentes tipos de recursos terão lógicas de fusão diferentes.
Após a fusão, uma mensagem mostrará os recursos modificados na branch principal.
Visualizando e Revertendo Fusões na Branch Principal
Na "APIs" da branch principal, você pode visualizar as alterações trazidas por operações de fusão recentes verificando o histórico dos recursos. Você também pode ver de qual branch a fusão veio.
Você pode visualizar o conteúdo específico da modificação e compará-lo com outras versões. Essa função de histórico permite que você acompanhe o histórico de mudanças e reverta o conteúdo quando necessário.
Arquivando, Restaurando e Excluindo Branches
Após fundir uma branch, você pode acessar a página de gerenciamento de Sprint branch através de "Configurações" -> "Branches Sprint". Na página de gerenciamento, você pode visualizar uma lista de todas as branches Sprint no projeto e suas estatísticas. Você também pode realizar várias operações nessas branches, incluindo arquivar, restaurar e excluir branches de iteração.
Perguntas Frequentes sobre Branches Sprint no Apidog
1 Todos os tipos de APIs são suportados pela funcionalidade Sprint Branch?
Atualmente, apenas APIs HTTP são suportadas.
2. Quem pode criar uma branch de iteração?
Administradores e editores do projeto.
3. Quem pode acessar uma branch de iteração?
Administradores, editores e membros em modo de leitura.
4. Quem pode fundir alterações de uma branch de iteração?
Administradores e editores do projeto.
5. Uma branch de iteração pode ser fundida em outra branch de iteração?
Atualmente não suportado. Apenas a fundição na branch principal é suportada.
6. Ao trabalhar em uma branch de iteração, se a API na branch principal também mudar, o que acontecerá após a fusão?
Após a fusão, as mudanças na branch de iteração substituirão as mudanças feitas na mesma API na branch principal. Isso significa que quaisquer adições, exclusões ou modificações na API na branch principal serão substituídas pelo conteúdo na branch de iteração.
7. Existe uma maneira de puxar as atualizações mais recentes da branch principal para uma branch de iteração?
Esse recurso está em desenvolvimento e estará disponível em breve.
8. Se alguns recursos forem excluídos na branch de iteração, qual impacto isso terá na branch principal quando fundidos?
Se recursos inteiros como APIs ou modelos de dados forem excluídos, isso significa que esses recursos não estão mais associados à branch principal. Portanto, os recursos correspondentes na branch principal não serão afetados durante a fusão, o que equivale a nenhuma mudança.
Isso ocorre porque um princípio fundamental das branches Sprint é envolver apenas a modificação e adição de recursos. As operações de exclusão precisam ser realizadas diretamente na branch principal, e a branch Sprint não lida com operações de exclusão.
Se os recursos da API ou do modelo de dados na branch Sprint estiverem associados à branch principal, e você excluir alguns desses recursos (por exemplo, parâmetros, descrições), os recursos correspondentes na branch principal também serão excluídos após a fusão. Essa operação é equivalente a modificar os recursos na branch de iteração.
9. Se uma nova API com a mesma URL e parâmetros que uma API na branch principal for criada na branch de iteração, o que acontecerá após a fusão?
Embora a nova API criada na Sprint branch tenha a mesma URL e parâmetros que a API na branch principal, elas não estão associadas por padrão. Após a fusão, a branch principal adicionará essa nova API que é exatamente igual à da Sprint branch, mesmo que uma API com a mesma URL e parâmetros já exista na branch principal.
Portanto, se você deseja atualizar, testar ou modificar uma API existente, importe a API da branch principal para garantir que elas estejam associadas. Desta forma, se a API mudar, a API na branch principal também será atualizada sincronicamente após a fusão.
10. Posso reverter e restaurar o conteúdo de uma branch Sprint anterior?
Sim.
Se você precisar visualizar o conteúdo de uma iteração anterior por algum motivo, pode restaurá-lo do estado arquivado para o estado normal da branch (note o limite da branch Sprint).
Após a restauração, você poderá acessar a branch novamente na árvore de diretórios das APIs. Os dados na branch antes do arquivamento serão automaticamente mantidos inalterados. Se você deseja restaurar o conteúdo do histórico da branch, pode usar diretamente essa branch para fundir novamente na branch principal para completar a restauração.
Para recursos individuais, recomenda-se usar a função "Histórico" diretamente em "APIs" para retrocesso e restauração.
11. Posso compartilhar a documentação da API de uma branch Sprint com outras pessoas?
Para colaboração e compartilhamento internos, você pode compartilhar com membros que se juntaram ao projeto através de "Copiar Link de Colaboração". Atualmente, o compartilhamento externo da documentação da API não é suportado.
Conclusão
A funcionalidade "Sprint Branch" do Apidog otimiza o processo de design e teste de APIs. Ao criar branches independentes, as equipes podem desenvolver novos recursos, corrigir bugs e experimentar sem interferir na branch principal.