Quando a UI mostra dados errados, a aba Network do DevTools diz se a API retornou dados errados. Esse é um bug de backend. Se os dados certos foram exibidos incorretamente, o problema está no frontend. Esse único hábito de diagnóstico exige entender como requisições e respostas REST são estruturadas.

O conceito central: requisição e resposta

Uma API (Application Programming Interface) é uma forma de dois pedaços de software conversarem entre si. Uma REST API é um estilo específico de API que usa HTTP, o mesmo protocolo que seu browser usa para carregar sites.

A conversa sempre acontece da mesma forma:

1. Seu código (ou teste) envia uma requisição

2. O servidor processa e devolve uma resposta

É isso. Todo o resto são apenas detalhes sobre como essas duas coisas são estruturadas.

Anatomia de uma requisição HTTP

Toda requisição tem quatro partes:

1. Método (o verbo)

O método diz ao servidor o que você quer fazer:

| Método | O que faz | Como dizer |

|--------|-----------|------------|

| GET | Busca dados | "Me dá essa coisa" |

| POST | Cria algo novo | "Aqui está um dado novo, salve" |

| PUT | Substitui algo completamente | "Substitua isso pela minha nova versão" |

| PATCH | Atualiza parte de algo | "Mude só esse campo" |

| DELETE | Remove algo | "Delete isso" |

Um endpoint de bugs pode funcionar assim:

  • GET /bugs → lista todos os bugs
  • GET /bugs/42 → busca o bug #42
  • POST /bugs → cria um novo bug
  • PATCH /bugs/42 → atualiza o status do bug #42
  • DELETE /bugs/42 → deleta o bug #42

2. URL (o endereço)

A URL diz ao servidor com o quê você está trabalhando:

https://api.becomeqa.com/v1/users/123/orders

Decomposto:

  • https://api.becomeqa.com: o servidor
  • /v1: versão da API (comum, nem sempre presente)
  • /users/123: o usuário específico com ID 123
  • /orders: os pedidos dele

As partes após o domínio são chamadas de path. Números e IDs no path (como 123) são chamados de parâmetros de path.

Às vezes dados são passados na URL como parâmetros de query:

GET /users?role=admin&active=true&page=2

A parte ?role=admin&active=true&page=2 filtra e pagina os resultados sem mudar sobre qual recurso você está falando.

3. Headers

Headers são metadados enviados com a requisição. Você não os vê no browser normalmente (estão na aba Network). Os mais comuns:

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

  • Content-Type informa ao servidor em qual formato está o corpo da sua requisição
  • Authorization prova quem você é (mais sobre isso abaixo)
  • Accept informa ao servidor em qual formato você quer a resposta

4. Body

Requisições POST, PUT e PATCH geralmente incluem um body: os dados reais sendo enviados. REST APIs quase sempre usam JSON:

{
  "title": "Botão de login não funciona no mobile",
  "severity": "high",
  "steps": ["Abrir app no mobile", "Tocar em Login", "Nada acontece"]
}

Requisições GET e DELETE tipicamente não têm body.

Anatomia de uma resposta HTTP

O servidor responde com:

1. Código de status

Um número de 3 dígitos que diz o que aconteceu:

| Faixa | Categoria | Significado |

|-------|-----------|-------------|

| 2xx | Sucesso | Requisição funcionou |

| 3xx | Redirecionamento | Recurso movido, vá para cá |

| 4xx | Erro do cliente | Sua requisição está errada |

| 5xx | Erro do servidor | O servidor quebrou |

Os códigos mais importantes para testes:

| Código | Nome | Quando aparece |

|--------|------|----------------|

| 200 | OK | Sucesso padrão para GET |

| 201 | Created | POST que criou algo |

| 204 | No Content | Sucesso mas sem nada para retornar (DELETE) |

| 400 | Bad Request | Entrada inválida (campo faltando, formato errado) |

| 401 | Unauthorized | Não autenticado (sem token ou token inválido) |

| 403 | Forbidden | Autenticado mas sem permissão |

| 404 | Not Found | Recurso não existe |

| 422 | Unprocessable Entity | JSON válido mas falha na validação |

| 429 | Too Many Requests | Rate limit atingido |

| 500 | Internal Server Error | Crash não tratado no backend |

| 503 | Service Unavailable | Servidor fora ou sobrecarregado |

2. Headers de resposta

Similar aos headers de requisição: metadados sobre a resposta:

Content-Type: application/json
X-Request-Id: abc-123-def
Cache-Control: no-cache

3. Body da resposta

Os dados reais retornados, geralmente JSON:

{
  "id": 42,
  "title": "Botão de login não funciona no mobile",
  "severity": "high",
  "status": "open",
  "created_at": "2026-05-17T10:30:00Z"
}

Ou um erro:

{
  "error": "validation_failed",
  "message": "Title is required",
  "field": "title"
}

Autenticação: como APIs sabem quem você é

A maioria das APIs exige autenticação. Duas abordagens principais são comuns:

Bearer Token / JWT

Após o login, o servidor te dá um token: uma string longa que prova sua identidade. Você a inclui em cada requisição subsequente:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIn0.abc123

O servidor valida o token sem precisar buscar sua sessão em um banco de dados. Tokens expiram (geralmente de 15 minutos a 24 horas).

Padrão mais antigo. Após o login, o servidor define um cookie. O browser o envia automaticamente em cada requisição para aquele domínio. Você não o vê no corpo da requisição: o browser cuida disso.

API keys

Usadas para comunicação servidor a servidor. Uma chave estática no header:

X-API-Key: sk-1234567890abcdef

Como inspecionar chamadas de API no browser

Abra o DevTools → aba Network → filtre por "Fetch/XHR". Cada chamada de API que seu app faz vai aparecer aqui.

Clique em qualquer requisição para ver:

  • Aba Headers: headers da requisição, URL, método
  • Aba Payload: corpo da requisição
  • Aba Response: o que o servidor retornou
  • Código de status: na visualização em lista, a coluna com o número

É aqui que você depura "é um bug de frontend ou de backend?" Se a UI mostra dados errados, verifique o que a API realmente retornou. Se a API retornou os dados certos e a UI os mostra errado, é frontend. Se a API retornou dados errados, é backend.

Testando APIs: o que verificar

Ao testar um endpoint de API (seja manualmente ou com Playwright), verifique:

O código de status corresponde à expectativa

  • Criar um recurso → 201, não 200
  • Buscar um recurso → 200
  • Delete bem-sucedido sem conteúdo → 204
  • Entrada inválida → 400 ou 422, não 500

O body da resposta está correto

  • Os campos obrigatórios estão presentes
  • Os tipos de dados estão certos ("age": 25 e não "age": "25")
  • Os valores correspondem ao que foi enviado
  • Nenhum dado sensível vazado (senhas, IDs internos)

As respostas de erro são úteis

  • Erros 400 devem explicar o que estava inválido
  • Erros 404 devem confirmar que o recurso não existe
  • Erros 401 não devem revelar informações sensíveis de segurança

Os casos de borda se comportam corretamente

  • Lista vazia: retorna [] e não null
  • ID inexistente: retorna 404 e não 500
  • Body JSON inválido: retorna 400 e não 500
  • Ação não autorizada: retorna 403 e não 200 com body vazio

REST APIs no Playwright

O Playwright pode fazer requisições HTTP diretamente, sem browser:

test('criar usuário retorna 201', async ({ request }) => {
  const response = await request.post('https://api.becomeqa.com/users', {
    data: {
      name: 'Test User',
      email: 'test@example.com',
      role: 'member',
    },
  });

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

  const body = await response.json();
  expect(body.id).toBeTruthy();
  expect(body.email).toBe('test@example.com');
  expect(body).not.toHaveProperty('password'); // sem vazamento
});

Você também pode interceptar chamadas de API feitas pelo browser durante testes E2E:

test('trata erro de API adequadamente', async ({ page }) => {
  // Força a API a retornar um erro
  await page.route('**/api/users', (route) => {
    route.fulfill({ status: 500, body: JSON.stringify({ error: 'server error' }) });
  });

  await page.goto('/users');

  // O app deve mostrar estado de erro, não travar
  await expect(page.locator('[data-testid="error-banner"]')).toBeVisible();
});

Resumo do vocabulário essencial

| Termo | Significado |

|-------|-------------|

| API | Interface para software se comunicar |

| REST | Um estilo de API que usa HTTP |

| Endpoint | Uma combinação específica de URL + método (GET /users) |

| Requisição | O que você envia para o servidor |

| Resposta | O que o servidor devolve |

| Código de status | Número de 3 dígitos indicando sucesso ou falha |

| JSON | O formato de dados que REST APIs usam (texto, pares chave-valor) |

| Header | Metadado anexado a uma requisição ou resposta |

| Body | Os dados reais em uma requisição ou resposta |

| Bearer token | Credencial enviada no header Authorization |

| Parâmetro de path | Parte variável da URL (/users/123, onde 123 é o parâmetro) |

| Parâmetro de query | Filtros na URL após ? (?page=2&sort=asc) |

Entender REST APIs torna você um engenheiro de QA significativamente melhor. Você consegue ler tráfego de rede, diagnosticar se um bug é de frontend ou backend, e escrever testes de API que rodam 100 vezes mais rápido que testes de browser. Isso permite conversas mais produtivas com os devs quando registra bugs.

→ Veja também: Testes de API 101: Tudo que Todo Engenheiro QA Precisa Saber em 2026 | Códigos de Status HTTP que Todo Engenheiro QA Precisa Conhecer | Testes de API com Playwright: Além da Interface | Como a Internet Funciona para Testadores