Libertando-se da carreira solo: aprendendo a colaborar no desenvolvimento de APIs com o Postman

O desenvolvimento de API é uma grande parte do que adoro no software. Seja construindo integrações ou criando APIs para aplicativos da web desacoplados, geralmente somos apenas eu e o código .

Na maioria das vezes, trabalho como desenvolvedor solo de API. Seguir sozinho tem suas vantagens: decisões rápidas e controle total. Mas é uma faca de dois gumes, pois manter tudo na cabeça torna as transferências e a delegação complicadas. E trabalhar sozinho limita o tamanho e a complexidade dos projetos nos quais posso trabalhar. Afinal, sou apenas uma pessoa.

Postman é minha principal ferramenta para trabalho de API – envio de solicitações, gerenciamento de ambientes e execução de testes. Estou familiarizado com meu fluxo de trabalho solo. Mas comecei a me perguntar: em um ambiente de equipe, o que mais o Postman pode oferecer? Como isso pode melhorar a colaboração e agilizar o processo de desenvolvimento?

Para explorar essas questões, comecei a trabalhar em um exemplo de API, que chamo de “X Nihilo”.

Exemplo de API: X Nihilo

X Nihilo ajuda a gerar tweets de 280 caracteres com base nos parâmetros que você armazena ou envia. Você fornece um tópico, um objetivo, uma descrição do tom a ser adotado e uma descrição do público. Nos bastidores, a API enviará uma solicitação à API da OpenAI para preenchimento de texto, o que auxiliará na geração do tweet.

Além disso, você pode salvar as strings usadas para tom e público e reutilizá-las em solicitações de tweet subsequentes.

Vamos examinar meu fluxo de trabalho básico de desenvolvimento de API.

Indo sozinho: meu fluxo de trabalho solo

A primeira etapa no meu fluxo de trabalho é projetar a API e escrever uma especificação OpenAPI. No Postman, criei uma nova API e depois iniciei uma nova definição de API.

Depois de pensar um pouco (e trabalhar diretamente com o ChatGPT, o que foi ótimo para gerar uma especificação inicial do OpenAPI com base em minhas descrições), escrevi minha especificação:

Com minha especificação OpenAPI implementada, cheguei a uma bifurcação no caminho. Devo configurar um servidor simulado e alguns exemplos de solicitações e respostas para mostrar como seria interagir com esta API? Ou devo começar a escrever código de implementação?

Como desenvolvedor solo, só posso ser produtor ou consumidor de API em um determinado momento. Então decidi: não há necessidade de criar simulações – o consumidor em mim teria que esperar. Vamos escrever algum código!

Alguns momentos depois…

Usando Node.js com Express e conversando com um banco de dados PostgreSQL, implementei minha API básica. Aqui está um resumo de tudo que eu precisava construir:

• POST /signin recebe um username e password , autentica nos registros do banco de dados e, em seguida, retorna um JWT assinado, que pode ser usado em todas as solicitações subsequentes.
• POST /generateTweet gera um tweet de 280 caracteres (máximo). É preciso um topic (string) e um goal (string). Ele também usa um tone (string) ou um toneId (ID inteiro de um tom armazenado), junto com um audience (string) ou um audienceId (ID inteiro de um público armazenado). Sempre que sequências tone e/ou audience forem fornecidas, a API as salvará no banco de dados.
• GET /tones retorna uma lista de IDs de tons e strings correspondentes. GET /audiences faz o mesmo para strings de público reutilizáveis.
• DELETE /tones pega um ID de tom e exclui esse registro de tom. DELETE /audiences faz o mesmo para registros de audiência.

Após a implementação inicial, era hora de voltar ao Postman para começar a executar algumas solicitações.

Crie um ambiente com variáveis.

Primeiro, criei um novo ambiente chamado “Teste”. Adicionei variáveis para armazenar meu root_url junto com um username e password válidos.

Crie uma coleção e uma solicitação

Então, criei uma nova coleção e adicionei minha primeira solicitação: uma solicitação POST a /signin , para testar a autenticação.

Com meu servidor API rodando em uma janela de terminal, enviei minha primeira solicitação.

Sucesso! Recebi meu token, que precisarei em quaisquer solicitações futuras.

Criei uma nova solicitação, desta vez para gerar um tweet.

Certifiquei-me de definir a autorização para usar “Bearer Token” e forneci o token que acabei de receber da solicitação anterior.

Aqui está a resposta:

Funciona!

Resumindo a abordagem solo

Essa é uma prévia básica do meu fluxo de trabalho solo. Claro, eu faria algumas outras coisas ao longo do caminho:

• Escreva um script de pré-solicitação para executar uma solicitação /signin e, em seguida, defina uma variável de ambiente com base no token na resposta.
• Crie solicitações para todos os outros endpoints na especificação OpenAPI.
• Escreva testes para cada endpoint, certificando-se de cobrir meus casos extremos.

Se estou trabalhando sozinho, esse fluxo de trabalho básico me deixa bem perto da linha de chegada. Embora tudo bem, sei que provavelmente estou apenas arranhando a superfície dos recursos disponíveis no Postman. E sei que precisaria de muito mais do Postman se estivesse trabalhando em equipe.

O momento aha: Por que considerar o Postman para equipes?

E se eu não pudesse mais ser um desenvolvedor solo de API para X Nihilo? Isso pode acontecer por vários motivos:

• X Nihilo cresce em tamanho e complexidade, e um único desenvolvedor de API não é mais suficiente para suportá-lo.
• X Nihilo é apenas uma pequena parte de um projeto de API maior que envolve vários desenvolvedores de API ou talvez até várias equipes de API.

Nem todos os meus projetos de API para clientes serão pequenos que eu possa construir sozinho. Às vezes, precisarei fazer parte de uma equipe que cria uma API. Talvez eu até precise liderar a equipe de API.

Quando isso acontecer, eu precisaria deixar minha mentalidade solo para trás e deixar minha maneira solo de fazer as coisas no Postman. Isso me motivou a analisar os recursos relacionados à equipe do Postman.

Explorando os recursos da equipe do Postman (empresarial)

Postman tem um nível gratuito e oferece alguns recursos de colaboração limitados, que podem ser suficientes se você tiver uma equipe pequena (ou seja, não mais do que três desenvolvedores). Postman possui recursos adicionais como parte de seu nível Enterprise Essentials. Eles são ótimos para equipes de API em organizações maiores que usam o Postman de maneira geral.

Compartilhamento de espaço de trabalho

Um espaço de trabalho permite que suas equipes colaborem em vários projetos de API. Isso é ótimo se você tiver equipes diferentes trabalhando em APIs diferentes, mas essas APIs interagem entre si (o que normalmente é o caso em organizações de software maiores).

Os espaços de trabalho são excelentes para permitir a colaboração em tempo real. Os membros da equipe podem editar a documentação da API, trabalhar juntos na elaboração de solicitações ou na escrita de testes e criar um servidor simulado que toda a equipe possa usar. À medida que as edições são feitas, elas são sincronizadas com toda a equipe em tempo real.

Controle de versão

Embora eu me preocupasse com o controle de versão do meu código, como desenvolvedor solo de API, não me importava muito com o controle de versão de minhas coleções ou ambientes do Postman. Se eu mudar alguma coisa (modificar uma solicitação, atualizar um teste, remover uma variável de ambiente), sou o único afetado. Nada demais.

Quando você trabalha em equipe, você definitivamente quer saber quando as coisas mudam. E às vezes você precisa reverter as alterações. Felizmente, para equipes que usam o Postman Enterprise, o Postman oferece acesso a um changelog para coleções, espaços de trabalho e APIs. Você pode reverter coleções para momentos anteriores. Como desenvolvedor de API em equipe, você precisará disso. Na maioria das vezes, é porque Bob estragou a coleção. Às vezes, porém, você é Bob.

Acesso baseado em função e organização de usuários

Nem todos em um espaço de trabalho do Postman devem ter o mesmo nível de permissões. Alguns membros da equipe são testadores e precisam apenas enviar solicitações e executar testes, mas não modificá-los. Outros podem ser designers que só têm permissão para modificar as definições da API.

No Postman, você pode atribuir funções aos membros da equipe. Isso afeta o tipo de acesso e o nível de permissão que cada membro da equipe possui em uma equipe ou espaço de trabalho.

As equipes também podem ter espaços de trabalho privados, restringindo o acesso de outras pessoas de fora da equipe.

Também notei que o Postman Enterprise suporta “captura de domínio”. Basicamente, isso significa que você pode configurar todos os usuários da sua organização, dando acesso a todos do domínio (por exemplo) mycompany.biz .

Comentários e discussões inline

Postman tem um recurso de colaboração, que está disponível em todos os seus planos, não apenas no Enterprise Essentials. Esta é a capacidade dos membros da equipe adicionarem comentários às coleções (em pastas, solicitações, exemplos ou solicitações pull). Ser capaz de comentar e discutir diretamente no Postman é fundamental para o desenvolvimento de API em equipe. Como a maior parte do trabalho de desenvolvimento de API da sua equipe acontecerá no Postman, faz sentido discutir lá (em vez de no GitHub ou algum outro serviço externo).

Desenvolvimento de API em equipe: Carteiro para a vitória

Sempre que entro em uma equipe, trago as ferramentas que adoro usar, mas não as empurro para meus colegas de equipe. Acho que eles têm suas próprias ferramentas. Então, cada um com o seu. Mas tenho a sensação de que a maioria dos desenvolvedores de API tem o Postman em seu conjunto de ferramentas. Seria uma pena se vários desenvolvedores de API em uma equipe usassem o Postman individualmente, com uma mentalidade individual e sem tirar proveito de alguns desses recursos de equipe. Se eles aproveitassem as vantagens dos recursos do Postman Enterprise, eles obteriam…

Maior eficiência

Em um espaço de trabalho compartilhado, você começa com a definição de API compartilhada. Sempre que um membro da equipe edita a definição (ou documentação, testes ou ambientes), as edições são sincronizadas e todos têm o que há de melhor e mais recente.

Todos trabalham com o mesmo conjunto de solicitações em uma coleção e todos têm acesso a todos os testes que serão utilizados. Todas essas conveniências melhorarão a eficiência de uma equipe, o que, por sua vez, aumentará rapidamente sua velocidade de desenvolvimento.

Menos mal-entendidos

Quando todos trabalham a partir da mesma fonte de verdade (seu espaço de trabalho) e podem fazer comentários e conversar dentro da ferramenta que estão usando para desenvolvimento, isso levará a menos mal-entendidos. Sua equipe não perderá tempo com confusão sobre se esse endpoint deveria receber parâmetros de consulta ou parâmetros de caminho. Tudo ficará claro.

Conclusão importante

Eu não sabia que o Postman era para equipes e empresas. Agora que sei, aqui está minha grande conclusão: os jogadores da equipe usam ferramentas que são boas para a equipe.

Postman tem sido ótimo para mim quando sou um desenvolvedor solo de API. Felizmente, ele também possui recursos que seriam ótimos para mim quando estou em uma equipe de desenvolvimento de API. Para mim, isso é sincronização em tempo real de edições em coleções, registros de alterações e controle de versão, além de permissões granulares de acesso. Agora estou animado para assumir projetos de API maiores com equipes maiores.

Boa codificação!

Também publicado aqui .