O que é uma API REST? Um Guia Prático para Engenheiros QA

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:

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:

Os códigos mais importantes para testes:

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).

Sessões baseadas em cookie

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

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