Testes de API 101: Tudo que Todo Engenheiro QA Precisa Saber em 2026

Quando você testa pela UI, está testando a API indiretamente: a UI chama a API por você, escondendo modos de falha que existem apenas na camada HTTP. Testar a API diretamente significa enviar requisições HTTP sem um navegador, o que expõe o que acontece com campos obrigatórios faltando, tokens de autenticação inválidos, ou IDs que não existem.

O que é uma API do ponto de vista dos testes

Você pode pensar em uma API como um contrato. Um sistema diz: "Me envie uma requisição nesse formato, e eu vou te dar uma resposta naquele formato." Seu trabalho como QA engineer é verificar que o contrato é mantido: que o sistema realmente entrega o que promete, rejeita o que deve rejeitar, e falha de forma elegante quando as coisas dão errado.

Na prática, a maioria das APIs que você vai testar são REST APIs que se comunicam via HTTP. Um app de reservas de viagem tem um endpoint de API que cria uma reserva. Um sistema de gerenciamento de usuários tem um endpoint que retorna uma lista de usuários. Uma plataforma de e-commerce tem endpoints para adicionar ao carrinho, verificar estoque e processar pagamentos.

Quando você testa pela UI, está testando a API indiretamente: a UI chama a API por você. Quando você testa a API diretamente, remove a UI da equação completamente. Isso significa testes mais rápidos, mensagens de falha mais claras, e a capacidade de testar cenários que a UI não expõe. O que acontece se alguém envia um preço negativo, um campo obrigatório vazio, ou uma requisição sem autenticação?

Fundamentos de HTTP para testers

Cada interação com uma API é uma requisição HTTP seguida de uma resposta HTTP. Aqui está o que cada lado contém.

Uma requisição tem quatro partes: o método, a URL, os headers, e um corpo opcional.

O método diz ao servidor que operação você quer executar. Os quatro que você vai usar constantemente são GET (recuperar dados), POST (criar algo novo), PUT ou PATCH (atualizar algo), e DELETE (remover algo). Enviar um GET para /api/users retorna uma lista de usuários. Enviar um POST para /api/users com dados do usuário no corpo cria um novo usuário.

A URL é o endereço do recurso. Geralmente tem uma base como https://api.exemplo.com, um caminho como /users/42, e às vezes query parameters como ?status=active&page=2.

Os headers carregam metadados: o tipo de conteúdo do corpo (Content-Type: application/json), credenciais de autenticação (Authorization: Bearer eyJ...), e instruções ao servidor sobre qual formato o cliente aceita (Accept: application/json).

O corpo contém os dados que você está enviando, tipicamente como JSON para REST APIs modernas.

Uma resposta espelha essa estrutura. Tem um status code, headers e um corpo. O status code é a parte mais importante para os testes:

• 200 OK: requisição bem-sucedida, aqui está o que você pediu
• 201 Created: algo foi criado com sucesso
• 400 Bad Request: sua requisição estava malformada ou com campos obrigatórios faltando
• 401 Unauthorized: você não está autenticado
• 403 Forbidden: você está autenticado mas não tem permissão para isso
• 404 Not Found: esse recurso não existe
• 422 Unprocessable Entity: a requisição estava bem formada mas é semanticamente inválida
• 500 Internal Server Error: o servidor quebrou

O que testar em uma API

O instinto é testar apenas o caminho principal: enviar dados válidos, receber um 200 de volta, pronto. Essa abordagem captura talvez 20% dos bugs. Aqui está um framework mais completo.

Um modelo mental útil: para cada endpoint, faça três perguntas. O que deveria funcionar? O que deveria falhar? Como deveria ser o erro quando falhar?

Ferramentas: Postman, Playwright e curl

Três ferramentas cobrem a maior parte do que você precisa.

# Requisição GET
curl https://lab.becomeqa.com/api/items

# POST com corpo JSON
curl -X POST https://lab.becomeqa.com/api/items \
  -H "Content-Type: application/json" \
  -d '{"destination": "Tokyo", "status": "planned"}'

# Com header de Authorization
curl https://lab.becomeqa.com/api/items \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

import { test, expect } from '@playwright/test';

test('POST /api/items cria um novo item', async ({ request }) => {
  const response = await request.post('https://lab.becomeqa.com/api/items', {
    data: {
      destination: 'Tokyo',
      status: 'planned'
    }
  });

  expect(response.status()).toBe(201);

  const created = await response.json();
  expect(created).toHaveProperty('id');
  expect(created.destination).toBe('Tokyo');
});

O fluxo é: explore com Postman e curl, automatize com Playwright.

Anatomia de um teste de REST API

Um bom teste de API verifica mais do que apenas o status code. Aqui está o que verificar em cada resposta.

O status code é o primeiro gate. Acerte antes de verificar qualquer outra coisa. Se o status está errado, todo o resto é irrelevante.

A estrutura do corpo da resposta importa. Se a API promete retornar um objeto de usuário com id, email e role, seu teste deve verificar que os três campos estão presentes em cada resposta. Isso captura regressões silenciosas onde alguém adiciona um campo obrigatório ao contrato do frontend mas esquece de incluí-lo na resposta da API.

Os valores dos campos importam, não apenas a existência dos campos. Se você criou um usuário com email test@exemplo.com, a resposta deve refletir exatamente esse email. Se a API retorna um campo de status, verifique que é um dos valores esperados, não apenas qualquer string.

Os headers da resposta carregam informações também. Verifique Content-Type: application/json se estiver esperando JSON. Para endpoints que retornam dados paginados, verifique headers de paginação como X-Total-Count ou links no corpo da resposta.

O tempo de resposta é um sinal. O Playwright não oferece assertions de tempo de resposta nativamente, mas você pode medir manualmente. Um endpoint que normalmente responde em 50ms retornando em 2000ms vale sinalizar mesmo que os dados estejam corretos.

Autenticação em testes de API

Quase toda API em produção exige autenticação. Os dois padrões que você vai encontrar diariamente são API keys e Bearer tokens.

curl https://api.exemplo.com/data \
  -H "X-API-Key: sua-api-key-aqui"

Nos seus testes automatizados, nunca hardcode a chave. Armazene em uma variável de ambiente e leia a partir daí. Isso mantém segredos fora do seu código de teste e facilita trocar entre credenciais de staging e produção.

Testar casos extremos relacionados a auth (tokens inválidos, tokens faltando, tokens com permissões erradas) é um dos testes de API de maior valor que você pode fazer. As consequências de errar na auth são severas, e esses bugs frequentemente vivem na API, não na UI onde seus testes de UI os capturariam.

Onde os testes de API se encaixam na pirâmide de testes

A pirâmide de testes é um modelo para como distribuir seus testes. Na base: muitos testes unitários, rápidos e baratos, testando funções individuais. No meio: testes de integração e API, testando como os sistemas se comunicam. No topo: poucos testes de UI, testando jornadas completas do usuário.

Os testes de API ficam no ponto certo. São significativamente mais rápidos que os testes de UI. Um teste de API típico roda em 50 a 200 milissegundos versus 3 a 10 segundos para um teste de UI. São mais estáveis porque não quebram quando o rótulo de um botão muda ou um seletor CSS se desloca. E testam a camada onde a maioria dos bugs de backend realmente vive.

Uma divisão prática para uma aplicação web típica: para cada 1 teste de UI cobrindo um fluxo de usuário, escreva 3 a 5 testes de API cobrindo os endpoints subjacentes. O teste de UI verifica que as peças se conectam corretamente. Os testes de API verificam que cada peça funciona corretamente sozinha.

Isso importa mais para a lógica de negócio. Se um app de e-commerce calcula descontos no backend, teste esse cálculo via API, não preenchendo um formulário de checkout em um navegador. O teste de API será dez vezes mais rápido e testará todos os casos extremos (zero itens, cupons expirados, descontos acumulados) sem nenhuma fragilidade de UI.

Como aplicar isso já na segunda-feira

Você não precisa refatorar toda a suite de testes. Aqui está como começar pequeno esta semana.

Escolha uma feature que tem testes de UI mas nenhum teste de API. Olhe o tráfego de rede no Chrome DevTools enquanto usa essa feature. Você vai ver as chamadas de API que a UI faz. Escolha o endpoint mais importante (geralmente o que cria ou recupera os dados principais) e escreva um teste de API para ele no Postman primeiro.

Verifique o caminho principal. Depois escreva um teste para um 404 (requisite um recurso por um ID inexistente). Depois escreva um teste para um 400 (envie um POST com um campo obrigatório faltando). Três testes que levam 30 minutos para escrever, e você estabeleceu o padrão.

Em seguida, mova esses três testes para o Playwright para que rodem no CI junto com seus testes existentes. Use a estrutura de código dos exemplos neste artigo. Rode-os uma vez para confirmar que passam.

A partir daí, expanda a cobertura perguntando: "Qual é o próximo endpoint mais importante?" e "Que casos de erro esse endpoint tem que não estou testando?"

Em algumas semanas, você terá uma camada de testes de API que captura bugs de backend em segundos, não via testes de UI que rodam por minutos. Esse é o benefício prático de tratar os testes de API como uma atividade de primeira classe, não como um fallback quando a UI quebra.