Uma boa documentação de uma API é de extrema importância para o seu sucesso, bem como exemplos claros e concisos de seu uso, dos tipos de dados aceitos e valores opcionais isso tudo e uma constante atualização dos dados para manter a documentação consistente com as ultimas versões. Por este motivo, existem ferramentas que auxiliam muito e justamente sobre isso que vamos falar neste artigo.
Um utilitário, que na minha opinião merece especial atenção quando vamos lidar com APIs em geral, é o POSTMAN (https://www.postman.com/downloads/) com ele é possível realizar requisições para APIs, testes automatizados em APIs e também mais de uma dezena de funcionalidades relacionadas a APIs em geral como criar chamadas e requisições em diversas linguagens de programação, além de permitir a escrita e compartilhamento de toda a documentação de uma API de maneira rápida.
Para se ter uma ideia, você pode ir gerando a documentação no mesmo momento em que está realizando os testes da sua plataforma, lá durante o desenvolvimento mesmo você termina a API e já termina a documentação. Então, sem mais delongas, vamos conhecer os recursos desse software e ambiente web (tem a versão web e também a versão para linux, windows e MacOS).
Em que ele te auxilia?
Você pode usar o software para criar requisições em praticamente qualquer API, usando diversos métodos de autenticação, verbos http, certificados digitais e criptografia. É possível visualizar os dados em uma série de formatos como HTML, XML, JSON, UML, RAW, CSV, TEXTO entre outros.
Um recurso interessante, são as possibilidades de criar um teste automático, gerando requisições completas e incompletas, alterando tipos de dados, variáveis e automatizando respostas e requisições, salvando os dados e podendo comparar com respostas pré-definidas. Muito útil, para desenvolvimento e integração continuada, para verificar se novas funcionalidades não quebram requisições anteriores.
Ao desenhar uma API é possível utilizar esquemas pré determinados, que podem servir como um guia para verificar já realizando testes de performance e produzindo documentação prévia, além de permitir que você publique a sua API em uma interface própria da plataforma que pode ser acessada por qualquer um (publica) ou você pode definir alguns níveis de acesso a ela.
Nos recursos, é possível criar TEAM (TIME) de desenvolvimento ou fazer parte de um que desenvolvem juntos e compartilham e publicam informações com níveis de acesso e controle sobre a publicação. Além de possuir uma API aberta que possibilite que seu fluxo de trabalho possa ser integrado aos recursos da plataforma.
Principais Recursos
A interface do aplicativo é bem simples e intuitiva, e a versão desktop possui mais recursos e controle que a versão web, possibilitando maior integração e mais recursos de personalização.
Seu ambiente é basicamente dividido em 3 partes, a barra superior que te dá acesso aos principais recursos e comandos, além de permitir a personalização da interface.
A lateral esquerda, que permite acesso ao histórico de requisições, e as coleções que você salvou no seu ambiente pessoal ou time, a as ferramentas para acesso e criação da documentação separadas em pastas (conjuntos) e subconjuntos de recursos, gerando uma infra-estrutura bem complexa e extensa para uma infinidade de ambientes e condições diferentes.
Por fim, a área principal que permite criar as requisições e executar além de permitir visualizar as respostas. A parte superior da aba, permite que você configure os endereços e end-points, e também toda a manipulação de cabeçalhos, corpo da requisição (body), autenticação, cookies aceitos e enviados e todos os recursos necessários e disponíveis para manipulação da requisição.
A parte inferior desse quadro possui as respostas recebidas da requisição, mostrando dados, cabeçalho http, cookies, corpo (body) e uma possibilidade de visualizar nos formatos diferentes vistos anteriormente. Recursos como código de resposta, e benchmarks com tempos de resposta são facilmente acessados.
O painel central, pode possuir diversas abas abertas, cada uma com uma requisição para a mesma coleção ou coleções diferentes. O recurso de busca (Ctrl + F) permite buscar dados dentro de uma ou de várias coleções, seja pelo nome de variáveis definidas, ou de valores digitados ou mesmo palavras presentes na documentação. Principalmente para adicionar ou editar a lista de códigos de erros e mensagens padrão.
Alguns recursos exigem que você tenha uma conta no serviço, em um plano gratuito para utilizar. Além de acesso a sincronização dos dados e e criação de perfil para contribuições como em times ou em projetos públicos.
Criando a Documentação e Coleções de APIs
Uma solicitação de API permite que você recupere ou envie dados em uma fonte externa. São executadas em servidores Web e expõem terminais (endpoints) para oferecer suporte às operações que os clientes usam para fornecer sua funcionalidade.
Cada solicitação de uma API usa um método HTTP. Os métodos mais comuns são GET, POST, PATCH, PUT e DELETE. Onde:
– GET recuperam dados de uma API;
– POST envia novos dados para uma API;
– PATCH e PUT atualizam dados existentes;
– DELETE remove os dados existentes.
Você pode fazer solicitações de API e examinar as respostas sem usar um terminal ou escrever qualquer código. Quando você cria uma solicitação e clica em Enviar, a resposta da API aparece na interface do usuário do Postman. Vamos fazer um teste:
-Crie uma nova solicitação (+) no painel central
-Escolha o método GET
-Digite o endereço – postman-echo.com/get
-Clique em (SEND) enviar e veja a resposta na parte inferior. Simples Assim para você criar e manipular todas as requisições.
Você pode importar uma série de coleções de APIs públicas como a API do Twitter para explorar os recursos e visualizar as documentações, além de uma dezena de outras que se você é iniciante pode usar para entender seu funcionamento. Além claro de publicar a sua própria API para implementação de um serviço público gratuito ou não.
Se você já usa uma ferramenta ou possui uma documentação de uma API já pronta, você pode importar dados para o postman, que possibilita a importação de diversos formatos e fluxos de trabalho em outras ferramentas e formatos amplamente utilizados no mercado. Você também pode importar dados diretamente de repositórios GitHub e sincronizar neles suas documentações e arquivos.
Criando sua primeira coleção
As Coleções são um grupo de solicitações salvas que você pode organizar em pastas. Todas as solicitações enviadas no Postman aparecem na guia Histórico da barra lateral. Em pequena escala, a reutilização de solicitações na seção de histórico é conveniente. Em vez de vasculhar sua seção de histórico, você pode salvar todas as suas solicitações como um grupo para facilitar o acesso.
Para salvar uma requisição, você pode simplesmente clicar no botão SAVE ao lado. Para criar a coleção, a aba lateral esquerda possui os recursos, entenda que as pastas e subpastas podem possuir um grupo de requisições dentro, que geralmente compõem as requisições de um determinado recurso ou endpoint. Você pode usar marcação MARKDOWN nos comentários que serão apresentadas na descrição de sua documentação, gerando um recurso de integração e fluxo de trabalho muito simples e rápido.
O conceito de WORKSPACES permite que você crie diferentes áreas de trabalho, permitindo que você compartilhe recursos diferentes em cada uma delas, participando de diversos projetos simultâneos e cada qual organizado de maneira independente e sincronizado com a conta do postman na web e compartilhando recursos e permissões com grupos diferentes.
Criando as Requisições
Você pode criar e enviar solicitações para se conectar às APIs com as quais está trabalhando. Suas solicitações podem recuperar, adicionar, excluir e atualizar dados. Seja na sua própria API, ou integrando-se a uma API de terceiros, você pode experimentar as solicitações diretamente. Suas solicitações podem enviar parâmetros, detalhes de autorização e quaisquer dados corporais de que você precisar. Por exemplo, se você estiver construindo um aplicativo cliente (por exemplo, um aplicativo móvel ou web) para uma loja, você pode enviar uma solicitação para recuperar a lista de produtos disponíveis, outra solicitação para criar um novo pedido (incluindo os detalhes do produto selecionado) e uma solicitação diferente para fazer o login de um cliente em sua conta. Ao enviar uma solicitação, o Postman exibirá a resposta recebida do servidor da API de forma que você examine, visualize e, se necessário, solucione o problema.
O básico, é criar a requisição dentro de uma Coleção ou Pasta, definir o URL (endpoint) e o MÉTODO usado (GET, POST, PATCH ou métodos que você mesmo cria) escolher o tipo de autenticação e os dados de autenticação que podem ser dinâmicos ou fixos e serão replicados dessa maneira na documentação produzida. Além de se desejar manipular dados do corpo, cookies e outros detalhes das requisições. E pode editar um titulo e uma descrição (com markdown) para esse recurso. Diretamente no aplicativo. Quando você faz isso, você pode testar e já criar a documentação, e implementar os testes. Quando compartilhar a documentação, publicamente ou de maneira privada ou mesmo exportando os dados, o próprio app já cria os exemplos de código em uma grande gama de linguagens populares, como JavaScript, cURL, C, C#, Go, HTTP REQUEST, JAVA, NodeJS, ObjectiveC (swift), OCaml, PHP, PHP Objeto, PowerShell Script, Python, Ruby, Bash Script e outros.
Você pode adicionar descrições aos seus parâmetros e eles aparecerão para qualquer pessoa que compartilhe a solicitação (por exemplo, no seu espaço de trabalho) ou visualizando a documentação da API.
Você precisará enviar dados no corpo (body) com suas solicitações sempre que precisar adicionar ou atualizar dados estruturados. Por exemplo, se estiver enviando uma solicitação para adicionar um novo cliente a um banco de dados, você pode incluir os detalhes do cliente em JSON. Normalmente, você usará dados do corpo com solicitações PUT, POST e PATCH.
Se você estiver enviando dados corporais, certifique-se de selecionar os cabeçalhos corretos para indicar o tipo de conteúdo que sua API pode precisar para processar os dados recebidos corretamente. Para dados de formulário e tipos de corpo codificados por url, o Postman anexará automaticamente o cabeçalho Content-Type correto. Porém no envio de formatos específicos, ou fluxos de dados, pode ser necessário acrescentar MIME/Types específicos. Os formulários (FORM) frequentemente enviam dados para APIs como multipart / form-data. Você pode usar isso clicando em Corpo de dados do formulário. Os dados do formulário permitem enviar pares de valores:chave e especificar o tipo de conteúdo. Ou até mesmo pode anexar arquivos usando dados de formulário. Quando você faz chamadas API repetidamente que enviam os mesmos arquivos, o Postman mantém seus caminhos de arquivo para uso posterior. Isso também ajuda a executar coleções que contêm solicitações que requerem upload de arquivo.
Algumas APIs exigem que você envie cabeçalhos específicos junto com as solicitações, normalmente para fornecer metadados adicionais sobre a operação que você está executando. Você pode configurá-los na guia Cabeçalhos. Insira quaisquer pares de valores-chave de que você precisa e o Postman os enviará junto com sua solicitação. Conforme você digita, o Postman apresenta opções comuns que você pode usar para preencher automaticamente.
Autenticação
Se você estiver criando uma API, poderá escolher entre uma variedade de modelos de autenticação. Se você estiver integrando uma API de terceiros, a autorização necessária será especificada pelo provedor da API. Você pode passar os detalhes de autenticação junto com qualquer solicitação que enviar.
Os dados de autenticação podem ser incluídos no cabeçalho, corpo ou como parâmetros de uma solicitação. Se você inserir seus detalhes de autenticação na guia Autorização, o Postman preencherá automaticamente as partes relevantes da solicitação para o tipo de autenticação escolhido. Você pode usar variáveis e coleções para definir detalhes de autorização com mais segurança e eficiência, permitindo reutilizar as mesmas informações em vários lugares. Além de deixar na documentação somente o nome definido da variável.
Você pode clicar com o botão direito abrindo opções detalhadas para a composição da documentação, e da requisição, bem como outras opções avançadas.
Respostas
O visualizador de resposta do Postman ajuda a garantir a exatidão das respostas da API. Uma resposta da API consiste no corpo, cabeçalhos e código de status. Postman organiza o corpo e os cabeçalhos em diferentes guias. O código de status e o tempo de conclusão da chamada de API estão visíveis ao lado das guias. A resposta também contém a descrição padrão da especificação HTTP. No entanto, os autores da API também podem adicionar mensagens personalizadas.
Assim que a resposta for retornada, clique no botão Salvar resposta. Digite um nome para chamar sua resposta salva. Todas as respostas salvas para uma solicitação estarão disponíveis como exemplo sempre que você carregar a solicitação. Esse exemplo também pode ser disponibilizado na documentação gerada. Você pode ver ela em formato diferente como JSON, TEXTO, XML, HTML, RAW conforme o tipo de resposta.
Você pode clicar sobre a guia NETWORK da resposta e ver os detalhes de endereços e certificados e assinaturas digitais. O Postman calcula automaticamente o tempo que levou para a resposta chegar do servidor, o que é útil para alguns testes preliminares de desempenho. Tamanho da resposta é também calculado e dividido em tamanho da resposta de corpo e cabeçalhos. Os tamanhos de resposta são aproximados. Os cookies enviados pelo servidor são visíveis em uma guia dedicada.
Executando Coleções Inteiras
O Collection Runner permite que você execute todas as solicitações em uma coleção na ordem em que aparecem, e crie fluxos de trabalho de testes em suas execuções. Você pode definir scripts em sua coleção e eles serão executados para cada solicitação dentro dela. Variáveis de coleção permitem definir valores a serem usados em todas as solicitações na coleção. Você pode gerar documentação de API a partir de uma coleção e compartilhá-la publicamente, bem como adicioná-la à Postman API Network um site onde todas as documentações públicas podem ser pesquisadas e sua documentação lida.
Anexar um monitor a uma coleção permite agendar execuções de coleção. Se você adicionar exemplos às suas solicitações, poderá usar servidores simulados e endereços de homologação para retornar dados de amostragem durante o teste e o desenvolvimento.
As variáveis permitem que você armazene e reutilize valores em suas solicitações e scripts. Ao armazenar um valor em uma variável, você pode referenciá-lo em todas as suas coleções, ambientes e solicitações – e se precisar atualizar o valor, você só precisa alterá-lo em um lugar. O uso de variáveis aumenta sua capacidade de trabalhar com eficiência e minimiza a probabilidade de erro.
Por exemplo, se você tiver o mesmo URL em várias solicitações – mas o URL pode mudar – você pode armazená-lo em uma variável. Se a URL mudar, você só precisa alterar o valor da variável e isso será refletido em toda a sua coleção, onde quer que você tenha usado o nome da variável. O mesmo princípio se aplica a qualquer parte de sua solicitação onde os dados são repetidos.
As variáveis globais permitem que você acesse dados entre coleções, solicitações, scripts de teste e ambientes. Variáveis de coleção estão disponíveis em todas as solicitações em uma coleção e são independentes de ambientes, portanto, não mudam com base no ambiente selecionado.As variáveis de ambiente permitem que você adapte seu processamento a ambientes diferentes, por exemplo, desenvolvimento local versus teste ou produção. Apenas um ambiente pode estar ativo por vez. Variáveis locais são temporárias e acessíveis apenas em seus scripts de solicitação. Os valores das variáveis locais têm como escopo uma única solicitação ou execução de coleta e não estão mais disponíveis quando a execução é concluída. Variáveis de dados vêm de arquivos CSV e JSON externos para definir conjuntos de dados que você pode usar ao executar coleções via Newman ou o Collection Runner.
Para defini-las basta selecionar o texto que vai compor a variável, clicar com o botão direito e em SET AS VARIABLE como na imagem, a aba de escopo e valor será aberta e você pode preencher os detalhes.
DOCUMENTANDO E PUBLICANDO
Você pode gerar documentação automaticamente para suas APIs. Você pode compartilhar sua documentação de forma privada ou publicá-la na web. O Postman gera e hospeda documentação baseada em coleções, sincronizadas em tempo real e acessíveis através do navegador. Você pode usar a documentação para colaborar com membros da equipe e parceiros, ou para apoiar a adoção do desenvolvedor para suas APIs públicas.
O Postman irá preencher várias partes da sua documentação a partir das informações associadas à coleção relevante. O conteúdo do Markdown pode incluir estruturas e formatação padrão, como títulos, listas, imagens, links, negrito / ênfase, exemplos de código, aspas em bloco e tabelas. Você pode criar documentação a partir da coleção do Postman ou diretamente nos documentos ao visualizá-los no navegador da web, se estiver logado e com permissões para fazer essas alterações.
Você pode publicar a documentação da API para torná-la disponível para exibição pública por qualquer pessoa que tenha o link. A documentação publicada permite que qualquer pessoa que queira aprender como usar sua API para visualizar detalhes sobre endpoints, incluindo parâmetros, corpos de solicitação e resposta e código de exemplo.
Sua documentação pública sempre exibirá conteúdo atualizado representando o estado atual de sua coleção. Você não precisa repetir o fluxo de publicação cada vez que quiser atualizar sua documentação.
