O que é uma API REST: explicação simples com exemplos do dia a dia

Atualizado em 11 de outubro de 2026 · Leitura de 7 min

Edson Feitosa de Oliveira Junior Fundador e Engenheiro Líder · PruPru Digital Services

Uma API REST é uma forma padronizada de dois sistemas conversarem pela internet usando HTTP, o mesmo protocolo das páginas web. Um lado (o cliente, como um aplicativo de celular ou um site) faz um pedido para um endereço, e o outro lado (o servidor) responde com dados, quase sempre em JSON. Quando o app do banco mostra seu saldo ou o site de delivery lista os restaurantes abertos, é muito provável que exista uma API REST por trás.

Pense num restaurante: você não entra na cozinha, faz o pedido ao garçom seguindo o cardápio. A API é o garçom e o cardápio ao mesmo tempo. Ela define o que pode ser pedido, como pedir e o que vem de volta, sem que o cliente precise saber como a cozinha funciona por dentro. A seguir estão os conceitos que você precisa dominar para criar ou consumir APIs com segurança.

Recursos e URLs

Em REST, tudo gira em torno de recursos: as "coisas" do seu sistema, como clientes, pedidos, produtos. Cada recurso tem um endereço (URL). A convenção mais aceita é usar substantivos no plural e deixar a ação para o método HTTP:

GET    /clientes          lista clientes
GET    /clientes/42       busca o cliente 42
POST   /clientes          cria um cliente
PUT    /clientes/42       substitui os dados do cliente 42
PATCH  /clientes/42       altera parte dos dados do cliente 42
DELETE /clientes/42       remove o cliente 42
GET    /clientes/42/pedidos   pedidos do cliente 42

Evite URLs com verbos, como /criarCliente ou /deletarPedido?id=5. Elas funcionam, mas fogem do padrão e deixam a API mais difícil de entender. Filtros e paginação costumam ir na query string: /produtos?categoria=bebidas&page=2.

Métodos HTTP: o verbo do pedido

Seguro significa que o método não deve alterar nada no servidor. Idempotente significa que repetir a mesma requisição várias vezes deixa o servidor no mesmo estado que uma única vez. Isso importa na prática: se a conexão cair no meio de um PUT, o cliente pode reenviar sem medo. Se cair no meio de um POST de pagamento, reenviar pode gerar cobrança duplicada, e por isso APIs de pagamento costumam pedir uma chave de idempotência.

Status codes: a resposta em um número

Toda resposta HTTP traz um código de três dígitos. O primeiro dígito já diz muito: 2xx deu certo, 4xx o erro foi do cliente, 5xx o erro foi do servidor. Os mais usados:

• 200 OK: deu certo, e o corpo traz os dados.
• 201 Created: recurso criado. O ideal é devolver o cabeçalho Location com a URL do novo recurso.
• 204 No Content: deu certo e não há corpo, comum em DELETE.
• 400 Bad Request: dados inválidos ou mal formatados.
• 401 Unauthorized: falta autenticação ou ela é inválida.
• 403 Forbidden: autenticado, mas sem permissão para aquilo.
• 404 Not Found: o recurso não existe.
• 409 Conflict: conflito com o estado atual, como e-mail já cadastrado.
• 422 Unprocessable Content: formato correto, mas regra de negócio violada (algumas APIs usam 400 para isso).
• 500 Internal Server Error: falha inesperada no servidor.

Um erro clássico de iniciante é responder 200 com {"erro": "cliente não encontrado"} no corpo. Isso engana ferramentas, monitoramento e quem consome a API. Use o código certo e mande detalhes no corpo.

JSON: o formato dos dados

JSON é texto organizado em pares de chave e valor, fácil de ler para pessoas e para programas. Uma requisição para criar um cliente poderia ser assim:

POST /clientes HTTP/1.1
Host: api.exemplo.com.br
Content-Type: application/json

{
  "nome": "Maria Souza",
  "email": "maria@exemplo.com.br",
  "cidade": "Natal"
}

E a resposta:

HTTP/1.1 201 Created
Location: /clientes/43
Content-Type: application/json

{
  "id": 43,
  "nome": "Maria Souza",
  "email": "maria@exemplo.com.br",
  "cidade": "Natal"
}

Os cabeçalhos (headers) carregam informações sobre a requisição: o tipo do conteúdo (Content-Type), o formato aceito na resposta (Accept) e credenciais (Authorization).

Testando uma API na prática

Você pode experimentar sem escrever nenhum programa. O curl já vem no Windows 10 e 11 e na maioria das distribuições Linux. Num terminal (no Windows, use o Prompt de Comando ou chame curl.exe no PowerShell para evitar o apelido antigo de algumas versões):

curl -i https://api.github.com/users/octocat

O -i mostra também o status e os cabeçalhos. Para enviar JSON:

curl -i -X POST http://localhost:8080/clientes -H "Content-Type: application/json" -d "{\"nome\":\"Maria\",\"email\":\"maria@exemplo.com.br\"}"

Ferramentas gráficas como Postman, Insomnia ou Bruno fazem o mesmo com interface visual, e o próprio navegador mostra as respostas de qualquer GET na aba Rede (F12).

O que torna uma API "REST"

REST é um estilo de arquitetura, não uma biblioteca. Na prática, as características que mais aparecem no dia a dia são:

• Cliente e servidor separados: o front-end pode mudar sem mexer na API, e vice-versa.
• Sem estado (stateless): cada requisição traz tudo o que o servidor precisa para atendê-la, como o token de autenticação. O servidor não depende de lembrar a requisição anterior.
• Interface uniforme: recursos identificados por URL e manipulados pelos métodos HTTP padrão.
• Respostas que podem ser cacheadas, quando fizer sentido, usando cabeçalhos HTTP.

Erros comuns de quem está começando

• Usar GET para alterar dados. Robôs, pré-carregamento do navegador e caches podem disparar GETs sozinhos.
• Expor a entidade do banco inteira, incluindo campos como senha ou dados internos. Use objetos de resposta próprios.
• Mensagens de erro inconsistentes, cada endpoint com um formato diferente. Padronize, por exemplo com o formato Problem Details (RFC 9457).
• Retornar listas sem paginação. Com mil registros funciona; com um milhão, derruba o servidor.
• Ignorar HTTPS. Tokens e dados pessoais trafegando sem criptografia podem ser interceptados. Veja por que todo site precisa de certificado SSL.
• Confundir 401 com 403, e esquecer que proteções como CSRF podem bloquear POST em aplicações com sessão. Um caso real está em Spring Security retornando 403 em POST.
• Não versionar. Mudar o formato de um campo quebra apps que já estão em produção. Prefixos como /v1/ ajudam a evoluir sem quebrar ninguém.

Próximos passos

Se você quer criar sua própria API, o caminho natural no ecossistema Java é o Spring Boot. O tutorial Spring Boot para iniciantes: sua primeira API REST mostra do zero como montar controller, service, repository e tratamento de erros. Como quase toda API grava dados em banco, vale também aprender as consultas SQL essenciais.

Perguntas frequentes