Validação contínua em contratos de API com Postman
Não vamos a lugar algum sozinhos e softwares também não. Em tecnologia, assim como na vida, relacionamentos são importantes. Sistemas precisam se comunicar uns com os outros para formar uma solução que agregue valor. Imagine o cenário onde você possui um serviço de encomendas mas não possui os meios para entrega-las, então contrata um serviço que faça isso para você, o Deliveryman API. Como garantir que o serviço estará disponível e sempre retornará o que é preciso para prosseguir com sua operação? É no mínimo complicado garantir isso, certo? Pode ocorrer alguma instabilidade ou o serviço pode sofrer alguma alteração.
Existem algumas alternativas para diminuir a ocorrência de problemas como esses, como: Definir previamente um contrato entre o serviço externo e sua aplicação, o que torna simples a integração e permite a evolução de maneira sustentável com o uso de versionamento, o Swagger pode ajudar com isso. Mas ainda não há a completa certeza de que o serviço vai estar disponível ou o contrato não vai mudar com o tempo, afinal não depende de você. Mas você depende do serviço.
Podemos antecipar alguns problemas com a ajuda do Postman e suas ferramentas de teste e monitoramento. Então segue com leitura que lhe explico melhor como fazer.
Postman e o segredo que não lhe contaram na faculdade
Acredito que você já deve conhecer o Postman (caso não, get started here), talvez até use ele no dia a dia. Mas você conhece a fundo os benefícios dessa plataforma? Que vai além de ser apenas um cliente para execução de requisições HTTP.
A plataforma possui diversos recursos que ajudam a manter a qualidade de seus serviços desde a validação do contrato e monitoramento até a documentação e publicação. Irei focar nas ferramentas Monitor e Automated Testing para garantir o funcionamento do serviço de entregadores e antecipar possíveis problemas.
Encontrando entregadores com o Deliveryman API
Voltando para o nosso serviço: O Deliveryman API é o serviço externo de entregadores, você solicita um entregador informando o endereço de coleta e peso da encomenda e ele lhe disponibiliza o entregador mais próximo que seja capaz de carregar o peso informado, independe do meio de transporte. Pode ser caminhão, carro, moto ou bicicleta, tudo que você precisa é que a encomenda seja coletada para então seguir seu destino.
Vamos reproduzir essa solicitação dentro do Postman (você pode baixar a ferramenta desktop aqui) e então executar a requisição. Neste ponto o contrato entre os serviços ajudaria para que possamos saber quais informações devemos enviar (para saber mais sobre contratos recomendo o estudo sobre Swagger e a especificação Open API). Mas neste caso não temos um contrato bem definido, nosso fornecedor apenas informou que precisamos enviar o peso (weight) e o endereço de coleta (address) através de query parameters na URL do serviço deliveryman-api.herokuapp.com/api/v1/deliveryman/find?address=250&weight=30 utilizando o verbo GET. O número 250 passado no address é apenas uma representação, poderia ser as informações de latitude e longitude do ponto de coleta por exemplo.
Na imagem a cima podemos ver a representação da requisição por um entregador. Utilizamos o verbo GET no serviço de find do deliveryman API, informando os dados necessários e o retorno foi o carro mais próximo com sua posição atual e o tempo que levará para realizar a coleta. Agora vamos validar se o resultado está como esperado através de testes em Javascript.
Testes em Javascript com o Postman Sandbox
Agora com a requisição criada precisamos validar o resultado dela. Existe a possibilidade de criar testes para cada requisição ou para uma coleção de requisições. Uma collection agrupa requisições de mesmo contexto, isso possibilita compartilhar recursos entre elas, nesse caso temos uma collection com apenas uma requisição.
Com a ajuda do Javascript podemos escrever testes de forma simples e poderosa, podemos manipular a requisição, a resposta e realizar outras requisições.
Na aba Tests estão os test scripts, o core dos scripts é o objeto pm que roda em um sandbox environment do Postman. Neste ambiente há diversas funcionalidades como asserções de testes, bibliotecas utilitárias como a lodash, crypto-js e outras. Neste exemplo temos dois testes, o primeiro valida se o status da resposta é 200 para verificar se o serviço está no ar, o segundo valida se a resposta do serviço está como esperamos. Conseguimos essas informações acessando o objeto response dentro do pm.
Para validar se a resposta está correta podemos usar a biblioteca tv4. Basta criar o schema do json esperado identificando todas as propriedades, seus tipos e quais atributos são obrigatórios, neste caso consideramos todos os atributos importantes. Caso a resposta sofra qualquer alteração nosso teste irá falhar.
Na imagem a cima podemos ver que o serviço parou de retornar a previsão do tempo que o entregador levará para realizar a coleta, informação que consideramos essencial e deve sempre estar disponível, por este motivo o teste falhou e sinalizou o erro. Através dos comandos Ctrl + Alt + C acessamos o console da ferramenta onde teremos mais detalhes da requisição e da execução dos testes.
Para saber mais sobre scripts de teste há a sessão de snippets no lado direito dos testes, na qual há diversos exemplos de manipulação do pm:
Monitor: Se o serviço falhar você é o primeiro a saber
Para utilizar monitores no Postman é preciso ter uma conta, pois este recurso possui um web dashboard que só está disponível para usuários autenticados. Mas é possível fazer o cadastro e utilizar todas as funcionalidades de maneira gratuita com pequenas limitações.
Na imagem anterior estamos criando o monitor para o serviço de entregadores. Após escolher as requisições que serão executadas automaticamente podemos definir algumas configurações, como:
- O environment para rodar o monitor.
- Frequência e período das execuções.
- Quais regiões geográficas em que será executado o monitor.
- Alertas por email em caso de falha nos testes ou nas requisições.
- Tempo limite da resposta do serviço.
Há diversas configurações que podem ser feitas com o monitor, ele possibilita a análise de performance e disponibilidade. Após a definição de configurações o monitor começa a rodar conforme a frequência escolhida e o resultado é apresentado no web dashboard.
O gráfico mostra o histórico de execução do serviço, informando o horário da execução, a região onde foi executado, o tempo decorrido durante a requisição e os resultados dos testes. As três primeiras execuções falharam no teste de validação devido à ausência do atributo deliveryTime que deveria ser obrigatório.
Quando as execuções falham este alerta é disparado para o email informando que houve uma quebra na execução dos testes. Desta forma podemos tomar uma ação antes mesmo que alguma encomenda seja afetada. Neste caso podemos entrar em contato com o fornecedor para entender o motivo dessa mudança.
Depois de algum tempo o serviço foi corrigido e voltou a responder como esperado. Como houve mudança do estado do serviço o Postman gera outra notificação informando que o serviço está estável novamente.
E isso foi só a ponta do iceberg
O que vimos aqui é uma pequena parte dos recursos disponíveis na plataforma, existem diversos outros na versão free, como: documentação, mock servers, team workspaces, entre outros. Sem falar nas versões pro e enterprise. Se quiser aprender mais sobre a plataforma basta acessar o Learning Center onde está disponível toda a documentação com diversos exemplos. O serviço de entregadores está disponível neste repositório junto com o link para importação da coleção do Postman utilizada como exemplo.
Isso é tudo pessoal, espero ter ajudado a trazer mais qualidade e segurança em suas integrações entre serviços. Um grande abraço e que a força esteja com você!
