[Guia] Controle de Versão das Suas APIs no Postman

Manter revisões de API consistentes e bem documentadas é crucial para um desenvolvimento eficiente de APIs. No entanto, gerenciar inúmeras versões e colaborar efetivamente sobre mudanças dentro de uma equipe pode ser um empreendimento complexo.

Este guia explora as funcionalidades do sistema de controle de versão integrado do Postman, capacitando você a gerenciar efetivamente versões de API, agilizar a colaboração e manter um registro claro das modificações. Ao aproveitar esses recursos, você pode garantir um fluxo de trabalho de desenvolvimento de API mais organizado e eficiente.

O que é o Postman?

Postman atua como um centro central para o desenvolvimento de APIs, agilizando o processo para programadores. Sua ampla gama de recursos abrange capacidades de design, teste e documentação. Essa consolidação de funcionalidades consolidou a posição do Postman como a ferramenta preferida para desenvolvedores que lidam com uma ampla gama de projetos relacionados a API.

O que é o Controle de Versão do Postman?

O controle de versão do Postman permite que você e uma equipe criem e modifiquem uma API de forma colaborativa. O controle de versão se especializa em gerenciar:

Coleções de API: Coleções definem suas requisições de API, que incluem URLs, parâmetros, cabeçalhos e conteúdo do corpo.

Ambientes de API: As variáveis de ambiente de API são armazenadas dentro do controle de versão do Postman para serem usadas dentro de suas coleções. Isso permite que os usuários troquem facilmente entre ambientes de desenvolvimento, teste e produção.

Simulações de API: As simulações de API simulam a resposta do servidor para os pontos de extremidade da API, tornando-as úteis para fins de teste.

Funcionalidades do Controle de Versão do Postman

O controle de versão do Postman oferece uma variedade de recursos para os desenvolvedores maximizarem os processos de desenvolvimento de API, como:

Rastreamento de Mudanças

• Mantenha um histórico claro das modificações para suas coleções, ambientes e simulações.
• Identifique quem fez mudanças específicas e determine o timestamp exato para melhorar a responsabilidade e a colaboração.

Divisão e Mesclagem

• Inspirado pelos fluxos de trabalho do Git, o Postman permite que você crie uma cópia (fork) de um elemento (coleção, ambiente, simulação) para trabalho independente.
• Uma vez que as edições estejam completas, mescle facilmente suas alterações de volta na versão principal, agilizando a colaboração e integrando contribuições individuais.

Solicitações de Pull

• Promova um desenvolvimento transparente permitindo que os membros da equipe revisem as alterações propostas antes de mesclá-las na versão principal.
• Esse processo colaborativo ajuda a identificar e resolver potenciais conflitos antes que eles interrompam o fluxo de trabalho.

Histórico de Versões

• Acesse iterações passadas de suas coleções, ambientes e simulações.
• Esse registro histórico permite que você reverta para versões anteriores, se necessário, proporcionando uma rede de segurança em caso de modificações indesejadas.

Integração com Sistemas de Controle de Versão Externos

• Embora o sistema integrado do Postman se destaque na gestão de artefatos de API, ele também pode se integrar com sistemas externos como o Git.
• Essa sincronização permite que você gerencie mudanças em suas coleções do Postman junto ao seu repositório de código, promovendo uma fonte única de verdade para suas definições de API.

Demonstração Exemplar do Controle de Versão da API do Postman

Esta demonstração exemplar do controle de versão da API no Postman incluirá o uso de um repositório Git.

Criar uma API no Postman

Crie uma nova requisição clicando no botão New no canto superior esquerdo da janela do Postman. Selecione HTTP Request para criar uma nova requisição, como mostrado na imagem acima.

Insira o Método e os Detalhes da API

Inclua os detalhes da requisição da API que você deseja criar. Deve incluir componentes como a URL, métodos HTTP e parâmetros adicionais que a API exigirá.

Selecione as Configurações da Equipe

Continue clicando em Team Settings.

Selecione os Apps Instalados

Você será redirecionado para uma página da web para configuração adicional. Nesta página, localize Installed apps encontrado na lista vertical à esquerda. Se você tiver o GitHub Enterprise Server ou GitLab Self-Managed, então esses apps aparecerão nesta tela.

Insira a URL de Domínio do Repositório GitHub

Insira a URL de domínio do seu repositório GitHub, que deve se parecer com:

GitHub Enterprise Server: https://my-github-server.example.com

GitLab Self-Managed: https://gitlab.example.com

Criar App OAuth

De acordo com o provedor Git que você possui, siga as instruções para criar um app OAuth.

• Homepage URL - Insira a URL da homepage do Postman: https://www.postman.com
• Authorization callback URL ou Redirect URI - Insira a URL de callback de autorização fornecida no Postman: https://integration-oauth.pstmn.io/v1/api-git-callback.html
• Scopes - Certifique-se de selecionar os escopos apropriados ao criar o app OAuth para permitir que o Postman leia e escreva em seu repositório. Para o GitHub, selecione os escopos repo e user. Para GitLab Self-Managed, selecione o escopo api.

Uma vez que você tenha o app OAuth, copie seu ID do Cliente e Segredo para inseri-los no Postman.

Colaboração Simples e Direta com Apidog

Apidog é uma poderosa plataforma de desenvolvimento de API que pode ser uma excelente substituta para o Postman. Com uma colaboração confiável e um distinto sistema de controle de versão nativo do Apidog, os usuários podem trabalhar juntos em equipe para desenvolver APIs de forma profissional e eficiente.

Construindo APIs com Apidog

Com Apidog, você e sua equipe podem criar APIs em poucos cliques.

Para começar, pressione o botão New API, como mostrado na imagem acima.

Prossiga definindo as várias características da API. Esta seção permite que você:

• Especifique o Método HTTP: Selecione o método HTTP apropriado (GET, POST, PUT ou DELETE) para ditar a operação desejada do servidor.
• Defina a URL do Endpoint da API: Indique a URL específica do endpoint da API (ou endereço da API) que facilita a interação cliente-servidor.
• Incorpore Parâmetros (Opcional): Inclua um ou mais parâmetros que serão incluídos dinamicamente dentro da URL da API, permitindo solicitações personalizadas.
• Forneça uma Descrição Funcional: Elabore uma descrição concisa que esclareça a funcionalidade pretendida da API.

Controle de Versão com Apidog

Na seção Design da sua API, clique no pequeno ícone quadrado conforme mostrado na imagem acima. Isso o levará à seção de changelog da sua API.

Nesta lista, você pode selecionar qual atualização deseja visualizar.

Por fim, você pode observar as mudanças feitas de uma versão da sua API para outra. Você pode ver quando a mudança foi feita e por quem a mudança foi feita. Se em algum caso uma versão mais antiga da API for necessária, os usuários também terão a opção de revertê-la para uma versão mais antiga selecionada.

Conclusão

Aproveitar efetivamente as funcionalidades de controle de versão do Postman permite que os desenvolvedores cultivem um ambiente de desenvolvimento de API mais organizado e colaborativo. Este guia forneceu a você o conhecimento para rastrear mudanças, facilitar a colaboração em equipe através de recursos como divisão e mesclagem e manter um histórico claro das revisões de API.

Lembre-se, uma estratégia de controle de versão bem definida é fundamental para agilizar seu fluxo de trabalho, prevenir conflitos e garantir a evolução tranquila de suas APIs. Adote os recursos integrados do Postman e explore a possível integração com sistemas externos para estabelecer uma abordagem de controle de versão que capacite sua equipe de desenvolvimento.