Como usar o Postman para documentar uma API

Texto: Daivid Silverio
Imagem: Vinicius Rocha

Desenvolver um aplicativo muitas vezes exige algum tipo de integração com outro sistema já existente. Por exemplo, se você quiser que as pessoas comprem o seu serviço por meio do seu app, é preferível que você faça uma integração com uma plataforma de pagamento que está atuando no mercado (IUGU, Mercado Pago, etc). Essas integrações são muito úteis para que o desenvolvedor não precise criar determinada funcionalidade do zero (pagamentos, mapas, login com redes sociais, etc.), e sim, apenas integrar o aplicativo com um serviço já existente. Ou até mesmo se você quiser utilizar no seu app uma plataforma já usada pela sua empresa ou algum banco de dados que você possua. Essa integração é feita por meio do consumo de uma API. E isso também te ajuda a economizar seus recursos na hora da produção.

Nós já entendemos que essa API é necessária quando se trata das funcionalidades que precisam de uma integração com outro sistema. Mas, é necessário que você entenda também como funciona este trabalho na maioria das empresas de desenvolvimento, inclusive aqui na Jera.

Tem dois caminhos para desenvolver este material: você pode alocar a equipe da empresa para desenvolver isso ou fazer por conta própria. Porém, atente-se bem se você escolher a segunda opção, pois cada empresa de desenvolvimento possui algumas regras que devem ser seguidas quando se trata de produzir em conjunto. E o máximo de atenção a isso é essencial para você não perder tempo e dinheiro com algo que depois não poderá ser utilizado.

Na Jera, quando o cliente prefere desenvolver a parte da API, nós fazemos a seguinte exigência: entregar a API documentada e fornecer uma Collection do Postman. Mas para você fazer isso, primeiro você precisa aprender a usar o Postman, certo?

Postman é uma ferramenta que dá suporte a documentação das requisições feitas pela API. Ele possui ambiente para a documentação, execução e testes de APIs e requisições em geral. O objetivo deste texto é fornecer um guia introdutório para a criação de documentações vivas para a sua API por meio da plataforma Postman.

Saiba o que iremos aprender agora:

  • Criar Coleções
  • Criar Pastas
  • Criar Requests
  • Adicionar Parâmetros
  • Adicionar Headers
  • Criar e popular variáveis de ambiente/globais

Criar Coleções

Clique no ícone da pastinha para abrir um formulário para criar a coleção.

imagem-1

Preencha com o nome desejado para a sua coleção e clique em “Create”. Pronto! Coleção criada! Agora vamos adicionar algumas requests e pastas na sua coleção.

imagem-2

Criar Pastas

Clique no ícone de reticências para abrir o submenu da Coleção. Clique em “Add Folder” para Adicionar uma nova pasta.

imagem-3

Escreva o nome da pasta que você acabou de criar e clique em “Create” para salvar. Você pode usar essa funcionalidade para organizar melhor suas requests, de acordo com os recursos ou funcionalidade que sua API provê.

imagem-4

Criar Requests

Para criar uma request, basta você digitar o endereço da API que você está documentando na barra de endereço e selecionar o método HTTP que será usado na request.

imagem-5

Para salvar essa request na Coleção, clique em “Save”.

imagem-6

Um formulário irá aparecer, onde você poderá preencher o nome da request e informar em qual Coleção e Pasta você deseja salvá-la. Finalmente, clique no botão “Save” laranja pra salvar a request.

 

imagem-7

Adicionar Parâmetros

Por exemplo, vamos utilizar o POST para localhost:3000/users, que criamos na seção anterior.

Para informar os parâmetros da request, selecione o formato desejado: form-data, x-www-form-urlencoded, raw (Text, JSON, XML etc), binary.

Por exemplo, supondo os parâmetros de criação de um usuário:
name: Test
email: test@test.com
password: 123456

Para testar, basta clicar no botão azul “Send”. O resultado da Request vem na parte de baixo onde está escrito “Response”

Em form-data:

imagem-8

Em JSON:

imagem-9

Você pode observar a resposta na aba “Body”, seguida pelos “Cookies” e “Headers” da mesma.

No exemplo, eu criei um header chamado “TOKEN”, para a demonstração.

imagem-10

Adicionar Headers

Adicionar headers é ainda mais simples do quê adicionar parâmetros. Basta selecionar a aba “Headers”, ao lado de “Body”, logo abaixo a barra de endereço:
imagem-11Criei uma request adicional que exige um token de autenticação para fazer requests a recursos protegidos, como as informações do usuário, neste caso.
imagem-12

Caso a autenticação funcione, os dados do usuário são retornados. Podemos ver isto na imagem abaixo. 

imagem-13

Se acontecer o contrário, um erro é recebido, 401 (Unauthorized), que significa que não foi autenticado.

imagem-14

Criar e popular variáveis de ambiente/globais

Ficar escrevendo todos esses valores para parâmetros e headers pode acabar ficando um pouco tedioso dependendo da sua API. Principalmente, se ela possuir autenticação via tokens que podem mudar.

Para facilitar nossa vida um pouco, podemos fazer uso das variáveis de ambiente e da aba extra “Tests”, encontrada logo abaixo da barra de endereços.

Primeiramente, vamos criar um ambiente. Clique no ícone com uma engrenagem no canto superior direito e logo em seguida, Manage Environments.

imagem-15

Na janela que aparecer, clique no botão “Add”. Um campo para preencher o nome do novo ambiente irá aparecer. Preencha com o nome desejado e clique em “Add”.

imagem-16

A partir desse momento você também já pode adicionar as variáveis que eu havia comentado.

Vamos adicionar uma variável chamada “Last User Token”. Clique em “Add” ou “Update” (caso você voltar nessa tela e estiver adicionando novas variáveis).

imagem-17

Agora vamos voltar na request que havíamos criado na seção “Criar Requests”. Tendo a request selecionada, clique onde está escrito “No Environment” e selecione o nome do ambiente que você acabou de criar.

imagem-18

Em seguida, selecione a aba “Tests” para começar a facilitar a vida de quem for utilizar sua API.

Nessa aba você pode executar scripts javascript que serão executados após as requests. Assim, você poderá capturar os resultados contidos nos corpos e headers das suas respostas.

Como um exemplo bem simples, vamos capturar o e-mail do usuário contido no corpo da resposta e header TOKEN da mesma.

postman.setEnvironmentVariable(“Last User Email”, JSON.parse(responseBody).email); 
postman.setEnvironmentVariable(“Last User Token”, postman.getResponseHeader(“TOKEN”));

imagem-19

Agora podemos modificar o método que obtém informações do usuário para usar o header de autenticação. Para isso, utilize o Token salvo na variável de ambiente “Last User Token”

Selecione a request que precisa usar a variável de ambiente. Então, vá até o campo do Header, Parâmetros ou Corpo da Request e utilize a variável usando a notação {{Nome da Variável}} para recuperar o valor salvo.

No exemplo da autenticação, ficamos com: Authorization:Bearer {{Last User Token}}

imagem-20

Podemos usar esse mecanismo não apenas nos parâmetros, mas também nos parâmetros/corpos das requests.

Ex:

imagem-21

O postman também te possibilita salvar suas requests e coleções na nuvem. Ele também tem a capacidade de importar/exportar Coleções via um link único ou um arquivo .json. Basta clicar no ícone de reticências na coleção e escolher a opção “Export”.

imagem-22O Postman é uma ferramenta muito poderosa e fácil de ser utilizada. Pode ser usada como um meio de comunicação entre equipes de times/empresas diferentes quando houver necessidade de integração de APIs e com certeza tem o potencial de facilitar a vida de muita gente!

Mais exemplos e documentação oficial: https://www.getpostman.com/docs/ 

5 Práticas Fundamentais para aumentar a Retenção de Talentos na sua organização

Texto: Diego Ungari

A área de Gestão de Pessoas tem consolidado cada vez mais sua função estratégica junto às organizações. Contudo, para assumir esse papel encontra uma série de desafios. Um dos maiores é a criação e aplicação de práticas que garantam a retenção dos talentos contratados.

Em geral, muitas instituições têm dificuldade em entender as necessidades de seus colaboradores. Por isso, a área responsável pela gestão de pessoas não consegue definir o ponto de partida para melhorar a felicidade da equipe. E assim, consequentemente, muitas pessoas de alto potencial acabam saindo.

Pensando nisso, existe uma série de práticas adaptáveis a realidade de qualquer entidade e que podem garantir o aumento da retenção de talentos. A seguir listamos cinco pontos que consideramos fundamentais para isso:

1.  Atraia pessoas alinhadas à cultura da organização

Em primeiro lugar, toda instituição deve ter clareza sobre sua missão, visão e seus valores. Pois a partir disso poderá entender o que constitui sua cultura e buscar pessoas que se conectem a ela.

Durante o processo de seleção, é importante que seja dada atenção ao alinhamento entre o perfil do candidato, a cultura organizacional e a oportunidade de trabalho em aberto. Uma boa forma de se fazer isso é utilizar o modelo de entrevista por competências.

Com isso, será reduzida a possibilidade da pessoa contratada não se adaptar ao cotidiano do local de trabalho e sair precocemente.

2.  Cálculo do Turnover

O Cálculo do Turnover é uma importante ferramenta para que a equipe de Gestão de Pessoas consiga visualizar de forma concreta o índice de rotatividade na organização. Também ajuda a pensar em estratégias para melhorar a retenção de seus talentos.

A forma de realizar este cálculo, bem como a periodicidade e a porcentagem de turnover esperada, deve ser definida de acordo com a realidade da entidade. Mas pode-se tomar por base a fórmula abaixo:

(# Desligados Passivos ou Ativos)
____________________________________________________
# Total de Funcionários

Se o cálculo do turnover de desligados passivos (pessoas demitidas) for alto, em geral, isso representa problemas no processo de recrutamento e seleção. Se o cálculo de desligados ativos (pessoas que pediram demissão) for alto, isso se relaciona mais às práticas da empresa para manter seus talentos. Entretanto, ambos impactam diretamente na retenção.  

3.  Clima Organizacional

Podemos definir o clima organizacional como um conjunto de fatores internos que influenciam na percepção das pessoas sobre o ambiente de trabalho. Apesar de ser algo subjetivo, isto interfere de várias formas na motivação dos colaboradores. Por isso, a área de Gestão de Pessoas deve buscar constantemente analisá-lo.

A forma mais eficaz de identificar como anda o clima na sua instituição é por meio da Pesquisa de Clima Organizacional. Ela pode ser aplicada trimestralmente, semestralmente ou anualmente, dependendo da sua necessidade e realidade.

4.  Plano de carreira

Diversas entidades, encontram grande dificuldade em clarificar para seus funcionários os caminhos que eles podem seguir internamente. Isso acontece especialmente com as empresas de pequeno porte.

Sem essa clareza a tendência é que os bons profissionais busquem oportunidades externas que proporcionem seu crescimento. É importante que as organizações definam como podem contribuir para que as pessoas se desenvolvam profissionalmente após contratadas. Portanto, deve-se difundir entre os colaboradores um plano de carreira, para que entendam as oportunidades internas e o que precisam desenvolver para atingi-las.

5. Valorização de Pessoas

Por fim, é fundamental que os gestores compreendam que as pessoas não podem ser tratadas como meros recursos. Elas dependem de diferentes estímulos para se sentirem realizadas, motivando-as a continuarem na instituição.

Desse modo, deve-se buscar vários meios para que as pessoas sejam valorizadas e reconhecidas por seus esforços. A ideia de que apenas o salário basta para motivar a equipe torna-se cada vez mais ultrapassada. E quando o gestor não compreende isso, sem dúvidas, terá péssimos resultados e um baixo índice de retenção.