Postman: Testes de APIs como se eu tivesse 10 anos [part I —Analogias]

Portanto, é melhor não prometer do que fazer um voto e não cumprir a palavra empenhada. Eclesiastes 5:5

Estou novamente de volta.

Antes de chegar ao tema propriamente dito, gostaria de informá-los que tentarei escrever o mesmo post em inglês e espanhol para forçar um pouco essas habilidades, portanto, se eu cometer algum erro gramatical mais grave, seu feedback será muito bem vindo.

Voltando ao tema, deixe-me contextualizá-los um pouco de onde veio essa ideia:

Atualmente trabalho na AIS uma empresa bem interessante de Brasília focada em soluções mobile, Agile Coaching, Microservices, SOA, Big Data. Trabalhamos com uma série de linguagens de servidor como Java, Kotlin, NodeJS, Scala, R, Ruby, dentre outras.

Com uma abordagem focada em chapters e guilds começamos a nos organizar e ministrar fóruns para disseminação de conhecimento. O que eu havia percebido é que algumas palavras estavam com o significado confuso entre algumas pessoas, como no caso APIs.

Comecei a pensar em como disseminar o conhecimento, porém, sem tornar aquilo tão maçante e confuso quanto uma fala da professora do Charlie Brown.

Cheguei à conclusão que uma boa abordagem seria aquela que eu encontrava nos livros da série Use a Cabeça.

Vamos então começar com uma analogia para APIs: o garçom. Essa foi uma analogia que conheci na minha empresa, e resolvi expandir outros cenários.

Uma interação com uma API pode ser entendida na analogia da interação que realizamos com um garçom em um restaurante. Nesse exemplo, nos como clientes ou consumidores de um restaurante interagimos com um garçom (API), que por sua vez interage com outras pessoas para que o pedido que solicitamos chegue a nossas mãos em um tempo determinado.

A título de facilidade, usaremos uma API REST para exemplos futuros.

Outro ponto interessante de ressaltar é que existem outras interações no restaurante que muitas das vezes não percebemos, como a interação com a parte financeira, solicitação de alimentos da distribuidora, etc, sendo assim, a API do restaurante não se restringe apenas a quem desfruta de seus alimentos.

Linguagens Backend e Tempo de Resposta (SLA)

É interessante ressaltar que muita das vezes não temos acesso aos cozinheiros dos restaurantes. Se eles são japoneses, brasileiros, indianos, etc não é um grande problema para a gente, contanto que a comida chegue em nossas mesas.

Nessa analogia a cozinha seria nosso Backend, que poderia ter aumento ou diminuição de recursos dado dias da semana e feriado (escalabilidade), e o tempo de entrega do nosso pedido nos influenciaria na nossa experiência com o restaurante, algo como o SLA do nosso serviço.

HTTP Status Code

APIs REST deveriam seguir padrões e convenções como códigos de status de execução (HTTP Status Code). Caso você ainda não conheça isso, dê uma olhada nesse site, e tente não “perder” no mínimo 15 minutos.

Imaginemos então a seguinte conversa em um restaurante e seus “status”:

Cliente: Garçom, você poderia me trazer uma água?

Garçom: OK (HTTP Status Code: 200).

Cliente: Garçom, você poderia me trazer um suco de maracujá?

Garçom: No momento não estamos tendo suco de maracujá (HTTP Status Code: 404).

Cliente: Garçom, você poderia me trazer um suco de laranja então?

Garçom: Desculpe o transtorno, mas acabamos de ter um problema na nossa cozinha, e não vamos conseguir te atender (HTTP Status Code: 500).

Especificação de API

Imagine que cheguemos a um restaurante japonês e peçamos uma porção de sushi, e o garçom fala que não trabalha com sushi (HTTP Status Code: 501). Pedimos então uma porção de sashimi, e o garçom fala que também não trabalha com sashimi (HTTP Status Code: 501).

Poderíamos continuar pedindo várias e várias vezes ao garçom coisas e esperarmos a sua resposta, ou simplesmente perguntarmos se o restaurante tem algum cardápio para sermos mais assertivos nas nossas requisições.

Nesse caso, o cardápio funcionaria como uma espécie de documentação ou especificação do que o restaurante oferece.

Trataremos mais sobre especificações e documentações de APIs na segunda parte desse post, mas por enquanto, essa analogia já nos basta.

Já percebemos o que acontece quando o cliente faz uma requisição ao garçom que não pode ser processada, mas você já imaginou o problema de um cardápio desatualizado?

Uma vez fui a um restaurante com a minha esposa e após pedirmos um determinado drink do cardápio recebemos algo completamente diferente.

Chamamos o garçom e falamos a ele que não foi o que havíamos pedido pelo cardápio, e ele nos respondeu que o cardápio estava desatualizado, eles já não tinham mais o drink, e retornaram uma outra coisa.

Lembro-me de contestarmos ele que estava escrito no cardápio. Lembro-me também dele retornando o drink e tentando fazer uma fórmula parecida com o drink do cardápio, enfim, uma experiência não muito agradável, pois gerou uma expectativa em nós. Era melhor não ter o cardápio do que ele estar desatualizado.

No universo de APIs isso é muito comum. Muita das vezes a documentação de várias APIs está desatualizada em comparação ao que ela deveria fazer, o que só dificulta a interação do cliente com a API.

O que aprendemos?

• Um garçom seria uma API de interação com uma cozinha e demais serviços em Backend.
• O tempo de resposta do nosso pedido (SLA) no restaurante impacta na experiência que temos com ele.
• Existe uma convenção de status para nossa interação com APIs.
• Documentar sua API pode facilitar o cliente a interagir com ela.
• Não documentar sua API pode ser um problema para o cliente.
• Documentar errado sua API é um problema ainda maior. Era melhor que não tivesse prometido nada para não gerar expectativa errada.

Terminarei esse post por aqui, na próxima parte falaremos sobre testes de APIs com o Postman. Até lá