Teste de API para iniciantes: métodos HTTP, códigos de status e o que verificar
O básico para começar a testar APIs REST: como uma requisição funciona, os métodos HTTP, os códigos de status mais comuns e um checklist do que verificar em cada teste, com exemplos.
Boa parte dos sistemas modernos conversa por APIs: o aplicativo do celular, o site e os sistemas parceiros usam as mesmas "portas" para ler e gravar dados. Testar a API é testar o coração do sistema, e costuma ser mais rápido e estável do que testar só pela tela.
Como uma requisição funciona
Uma requisição HTTP tem quatro partes principais:
- Método: o que você quer fazer (buscar, criar, alterar, apagar).
- URL: onde, por exemplo
https://api.exemplo.com/pedidos/42. - Cabeçalhos: informações extras, como o formato dos dados (
Content-Type: application/json) e a autenticação (Authorization: Bearer ...). - Corpo: os dados enviados, geralmente em JSON (nem toda requisição tem).
A resposta traz um código de status, cabeçalhos e, quase sempre, um corpo.
Os métodos HTTP mais usados
| Método | Para quê | Exemplo |
|---|---|---|
| GET | Buscar dados | GET /pedidos/42 |
| POST | Criar | POST /pedidos com os dados no corpo |
| PUT | Substituir um recurso inteiro | PUT /pedidos/42 |
| PATCH | Alterar parte de um recurso | PATCH /pedidos/42 só com o campo que muda |
| DELETE | Apagar | DELETE /pedidos/42 |
Um detalhe que vale testar: GET, PUT e DELETE devem ser idempotentes, ou seja, repetir a mesma requisição não pode mudar o resultado além da primeira vez. Já um POST repetido costuma criar dois registros, e muitas vezes isso é um defeito (o famoso "pedido duplicado" por clique duplo).
Códigos de status que você vai ver o tempo todo
| Faixa | Significado | Códigos comuns |
|---|---|---|
| 2xx | Deu certo | 200 OK, 201 Created, 204 No Content |
| 3xx | Redirecionamento | 301, 302, 304 |
| 4xx | Erro de quem chamou | 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests |
| 5xx | Erro do servidor | 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable |
Uma regra prática: um erro causado por dados inválidos do cliente deve voltar como 4xx, nunca como 500. Um 500 em resposta a uma entrada inválida quase sempre indica um defeito: o sistema não tratou o erro.
Outra diferença que cai em entrevista: 401 significa "não sei quem você é" (falta autenticação ou ela é inválida); 403 significa "sei quem você é, mas você não pode fazer isso".
Um exemplo com curl
curl -i -X POST https://api.exemplo.com/pedidos \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SEU_TOKEN_DE_TESTE" \
-d '{"produto": "caneca", "quantidade": 2}'
O -i mostra os cabeçalhos da resposta, incluindo o código de status. Ferramentas como Postman e Insomnia fazem o mesmo com uma interface visual e permitem salvar coleções de requisições e escrever verificações automáticas.
O que verificar em cada teste
- Código de status correto para o cenário (201 ao criar, 404 para recurso inexistente etc.).
- Corpo da resposta: os campos esperados existem, com os tipos e valores certos. Vale conferir também o que não deveria aparecer, como senhas ou dados de outros usuários.
- Cabeçalhos: por exemplo,
Content-Typecorreto. - Efeito colateral: depois de um POST, um GET encontra o registro criado? Depois de um DELETE, ele some mesmo?
- Tempo de resposta dentro do esperado.
- Autenticação e permissão: sem token deve dar 401; com o token de um usuário sem permissão, 403.
Cenários que costumam revelar defeitos
- Campos obrigatórios ausentes, vazios ou com tipo errado (texto onde se espera número).
- Valores nos limites: quantidade 0, negativa, muito grande.
- Acessar o recurso de outro usuário trocando o id na URL (
/pedidos/43em vez de/pedidos/42). Se funcionar, é uma falha de segurança séria. - Repetir a mesma requisição de criação.
- Caracteres especiais e textos longos.
Os dois primeiros itens são aplicações diretas de particionamento de equivalência e análise de valor limite, que explicamos nas técnicas caixa-preta com exemplos.
Cuidados
- Teste em ambientes de teste, nunca em produção, a não ser que o time tenha um processo combinado para isso.
- Não compartilhe tokens reais em prints, chamados ou conversas com ferramentas de IA.
- Use dados fictícios.