Como fazer a

documentação da API
usando o Postman

MobiMais
 02/20

Sumário

Introdução 3
Cadastro no Postman 4
Instalando na área de trabalho 5
Criando nova collection 6
Configurando o environment        7
Configurando uma URL base 8
Área de requisições no Postman 11
Documentando sua requisição 12
Montando uma nova requisição 14
Teste da resposta da requisição 15
Compartilhando sua coleção 16
Importando uma coleção 18
 03/20

Este tutorial destina-se a demonstrar como usar a

ferramenta Postman, que auxilia o desenvolvedor no
teste, documentação e compartilhamento das APIs.

Nele, você pode salvar todos os seus

endpoints em coleções, configurando diversos
parâmetros, podendo enviar e receber
qualquer requisição HTTP, certificando que as
respostas do servidor são válidas.

Um cuidado a se tomar com a ferramenta é

que ela atua diretamente sobre a API, não é
uma simulação. Qualquer envio para a API
através do Postman será contabilizado.
Por exemplo, ao testar uma requisição de
cadastro de usuário, uma nova instância será
criada no banco de dados do servidor, então é
preciso estar atento à esse detalhe.

Caso já possua uma conta no Postman, pule

para a página 6.
 04/20

Cadastro no Postman

Para começar, vá até a página

www.getpostman.com

Caso não possua uma conta, cadastre-se em

“Sign-in”.

Com o cadastro feito, vamos baixar nossa ferramenta

de trabalho: o aplicativo Postman (apenas para Mac).
Caso você seja um usuário Windows, baixe o aplicativo
do Postman para Chrome. Usaremos a versão Free.
 05/20

Instalando na área
de trabalho

Se quiser que o aplicativo fique disponível em sua

área de trabalho, vá nas configurações do Chrome,
e procure o Postman, recém instalado, entre elas.

Clique em “Detalhes”,
“Criar atalho” e depois
confirme em “Criar”. Esse
processo criará um atalho
na sua área de trabalho.

Se você é um usuário de
MacOS, baixe e
descompacte, depois copie
e cole o aplicativo na pasta
de Aplicativos do seu Mac.
 06/20

Criando uma
nova collection

Para configurar uma nova API, será criado uma nova

coleção no Postman.
Dentro dessa coleção ficarão organizados todos os
endpoints que serão usados.
Para criar uma nova coleção, clique em “Collections”,
e em seguida clique no ícone +.

Dê à coleção um nome que reflita a aplicação para a

qual será usada, assim como uma breve descrição.
Usaremos como exemplo o nome “MobiBook” para
ilustrar esse processo.
 07/20
Configurando
o environment

Com a coleção criada, vamos

configurar nossa URL base.
No canto superior direito,
clique em “No environment”
e em seguida clique em
“Manage Environments”.

Na janela “Manage
Environments”
clique em “Add”.

Em seguida dê
um nome à seu
ambiente.
 08/20

Configurando
uma URL base

Nesse exemplo, usaremos um endpoint da API de

previsão do tempo do Yahoo, disponível em
https://developer.yahoo.com/weather/

Na Coluna "Examples" clique em "One word

conditions for Dallas, TX" e escolha "JSON" em
"Responses"."
 09/20
Configurando
uma URL base

Para configurar a URL, insira um valor chave e em

seguida o endereço que será usado como base para
toda a API. Para finalizar, clique em “Add”.

No exemplo, a chave é “URL_BASE”, e o seu valor será

https://query.yahooapis.com/v1/public/yql?q=select/

Usamos essa URL_BASE pois em qualquer requisição

de consulta de temperatura nessa API essa URL não
muda, bastando apenas alterar o restante do link para
se obter uma resposta diferente.
 10/20

Configurando
uma URL base

Com a URL base da API configurada, podemos

alterá-la a qualquer momento voltando no
environment criado. Isso facilita uma migração para
outra base, já que sem essa configuração teríamos
que alterar manualmente todas as requisições caso
a URL base precisasse de mudança.

Para criar nossa primeira requisição, certifique-se

de que o environment escolhido é o destinado à
coleção, no nosso exemplo o MobiBook.
 11/20
02/22
Área de requisições
no Postman

A configuração de uma requisição é feita nessa

área do Postman.

Aqui, podemos escolher:

1. O tipo requisição (GET, POST, PUT…)
2. Montar a URL base
3. Configurar as autorizações
4. Os Headers
5. O corpo (Body) a ser enviado
6. Aba para novas requisições
7. Outras configurações.

1 2
3 4 5
 12/20
Documentando
sua requisição

Para salvar a requisição que será criada, clique em SAVE.

Na documentação, é essencial manter padrões quanto aos

campos a serem preenchidos nesse passo. Na caixa de diálogo
aberta temos os seguintes campos:

1. Nome da requisição (Request Name): nesse campo coloca-se o

nome da requisição. É importante que esse nome reflita a ação
que o endpoint realizará, pra que fique fácil pra outro
desenvolvedor usar a API. Se por exemplo, o endpoint da
requisição cadastra uma pessoa num banco de dados, um bom
nome seria “Consulta Previsão Tempo”.
2. Descrição (Request Description): aqui deverá ser colocada uma
descrição do que o endpoint faz. O que é enviado e o que é
recebido pela requisição deve ser descrito brevemente, para que
fique claro o que está sendo feito nessa chamada.
3. Escolha de qual coleção será salva a requisição (Save to existing
collection): nesse campo você deve selecionar em qual coleção
será salvo o endpoint configurado.
4. Criar nova coleção (Or create new collection): Caso você não
tenha criado uma coleção, você pode criar uma nova e salvar nela
imediatamente usando esse campo. (Imagem na próxima página.)
 13/20
Documentando
sua requisição

4
 14/20

Montando uma
nova requisição

Vamos montar a nossa requisição exemplo:

Para montar a URL a partir da base, coloque a key
cadastrada no environment entre chaves duplas
(“{{URL_BASE}}”) e coloque o restante do endpoint a
seguir, o que no nosso caso é “%20item.condition.text
%20from%20weather.forecast%20where%20woeid
%20in%20(select%20woeid%20from
%20geo.places(1)%20where%20text%3D%22dallas
%2C%20tx%22)&format=json&env=store%3A%2F
%2Fdatatables.org%2Falltableswithkeys”, que fará o
acesso no servidor da API pela informação necessária.

Acesso ao endpoint

O tipo da nossa requisição exemplo é “GET”. Como nesse

exemplo não estamos enviando nenhuma informação, apenas
recebendo, não precisamos configurar os Headers nem o Body.
 15/20

Teste da resposta
da requisição

Para testar a resposta da nossa requisição teste clique

em SEND.

Na área abaixo você receberá o resultado da sua

requisição. Essa é uma das melhores vantagens do
Postman: Testar as requisições ao mesmo tempo em
que as documenta.
 16/20

Compartilhando
sua coleção

Para compartilhar sua coleção com seus colegas,

clique na seta.

Clique no botão SHARE.

 17/20

Compartilhando
sua coleção

Na caixa de diálogo, siga para “Collection Link” e

copie a URL dada.

O link gerado pode ser fornecido a outros

desenvolvedores para que eles tenham acesso às
requisições que você documentou. Para usá-lo, é
necessário realizar a importação dele dentro do Postman.
 18/20
Importando uma
coleção

Para importar uma coleção no Postman a partir de um

link fornecido, clique no botão import na barra
superior

Na caixa de diálogo que surgir, clique em “Import from

link”. Cole a URL compartilhada na área sugerida e em
seguida confirme a ação, conforme mostrado na figura
abaixo.

Assim, a coleção compartilhada será adicionada às suas coleções.

 19/20

Parabéns!

Você finalizou o tutorial da Mobi+ de como fazer a

documentação da API no Postman, usando nossa
metodologia!
mobimais.com.br mobimais.com.br/blog fb.com/mobimaisbr