API REST: O que é, Como Funciona e Exemplo Prático

API REST é uma interface que permite a comunicação entre sistemas usando recursos, representações e as regras do protocolo HTTP. Em uma API comum, o cliente envia uma requisição para um endereço e o servidor responde com dados, um código de status e cabeçalhos.

REST não é um protocolo nem um formato de arquivo. É um estilo arquitetural definido por restrições como cliente-servidor, ausência de estado de sessão entre requisições, cache, sistema em camadas e interface uniforme.

Resposta rápida: uma API REST normalmente representa entidades por URLs, usa métodos HTTP para indicar ações e retorna JSON com códigos como 200, 201, 400, 404 e 500. Uma implementação realmente RESTful também respeita as restrições arquiteturais do REST.

API, REST e RESTful são a mesma coisa?

Nem toda API HTTP com JSON é completamente RESTful. Muitas APIs utilizam URLs, métodos e códigos HTTP corretamente, mas não implementam hipermídia ou outras partes da definição original.

Para uma introdução mais ampla ao conceito, consulte também o que é uma API.

Quais são as restrições do REST?

• Cliente-servidor: interface e dados podem evoluir de forma independente.
• Stateless: cada requisição contém o contexto necessário para ser processada.
• Cache: respostas informam quando podem ser reutilizadas.
• Interface uniforme: recursos são manipulados por uma interface consistente.
• Sistema em camadas: clientes não precisam saber se falam diretamente com o servidor final, um gateway ou um proxy.
• Código sob demanda: restrição opcional em que o servidor pode enviar código executável ao cliente.

Stateless não significa que o servidor não tenha banco de dados ou estado persistente. Significa que ele não depende de um contexto de sessão oculto de uma requisição anterior para entender a requisição atual.

Recursos, URLs e endpoints

Uma API REST trabalha com recursos, como clientes, produtos e pedidos. As URLs devem identificar esses recursos. Os métodos HTTP indicam o que o cliente pretende fazer.

GET    /api/clientes
POST   /api/clientes
GET    /api/clientes/42
PUT    /api/clientes/42
PATCH  /api/clientes/42
DELETE /api/clientes/42

Prefira substantivos nas URLs. Em vez de /buscarClientes ou /deletarCliente/42, use o recurso /clientes com o método HTTP adequado.

Métodos HTTP em uma API REST

Um método é seguro quando sua semântica é essencialmente de leitura. Ele é idempotente quando repetir a mesma requisição produz o mesmo efeito pretendido no servidor que executá-la uma vez.

DELETE continua sendo idempotente mesmo que a segunda tentativa retorne 404. O efeito pretendido, deixar o recurso removido, permanece o mesmo.

Exemplo prático de API REST

1. Consultar um cliente

GET /api/clientes/42 HTTP/1.1
Host: exemplo.com
Accept: application/json

Resposta:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: "cliente-42-v3"

{
  "id": 42,
  "nome": "Ana Lima",
  "email": "ana@example.com",
  "ativo": true
}

2. Criar um cliente

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

{
  "nome": "Bruno Souza",
  "email": "bruno@example.com"
}

Uma resposta comum é 201 Created com o endereço do novo recurso no cabeçalho Location:

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

{
  "id": 43,
  "nome": "Bruno Souza",
  "email": "bruno@example.com",
  "ativo": true
}

3. Atualizar parcialmente

PATCH /api/clientes/43 HTTP/1.1
Host: exemplo.com
Content-Type: application/merge-patch+json
If-Match: "cliente-43-v1"

{
  "ativo": false
}

O cabeçalho If-Match pode evitar que uma alteração sobrescreva uma versão mais recente criada por outro usuário. O servidor compara o valor com o ETag atual antes de aceitar a mudança.

Códigos de status mais usados

Não retorne 200 para todos os resultados. Os códigos fazem parte do contrato e permitem que clientes, gateways e ferramentas entendam o que aconteceu.

Cabeçalhos importantes

• Content-Type: informa o formato do corpo enviado.
• Accept: indica quais formatos o cliente consegue receber.
• Authorization: transporta credenciais ou um token conforme o esquema usado.
• Cache-Control: define políticas de cache.
• ETag e If-Match: ajudam no cache e no controle de concorrência.
• Location: informa o endereço de um recurso criado ou de um redirecionamento.
• Retry-After: informa quando uma nova tentativa pode ser realizada em determinadas respostas.

Paginação, filtros e ordenação

Listas grandes não devem retornar todos os registros de uma vez. Um contrato simples pode usar parâmetros de consulta:

GET /api/pedidos?status=pago&page=2&limit=20&sort=-criado_em

A resposta deve informar como navegar para outras páginas. Para conjuntos que mudam com frequência, paginação por cursor pode evitar duplicações e saltos causados por novas inserções.

{
  "items": [],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIzfQ",
    "has_more": true
  }
}

Formato de erros

Defina um formato consistente para erros. Não exponha stack traces, consultas SQL, segredos ou detalhes internos.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "error": {
    "code": "EMAIL_INVALIDO",
    "message": "O email informado não é válido.",
    "fields": {
      "email": "Use um endereço no formato nome@dominio.com."
    },
    "request_id": "req_7f81a2"
  }
}

Autenticação e segurança

• Use HTTPS em todo o tráfego.
• Autentique a identidade e verifique autorização em cada recurso.
• Valide tamanho, tipo, formato e limites de todos os dados de entrada.
• Use consultas parametrizadas para acessar bancos de dados.
• Implemente limites de requisições e proteção contra abuso.
• Não registre tokens, senhas ou dados pessoais sem necessidade.
• Faça rotação de chaves e defina expiração para credenciais temporárias.

OAuth 2.0 é um framework de autorização. JWT é um formato de token e não representa sozinho uma estratégia completa de autenticação ou segurança. Uma API pode usar OAuth sem JWT e pode usar JWT sem OAuth.

Versionamento e documentação

Mudanças compatíveis, como adicionar um campo opcional, geralmente não exigem uma nova versão. Alterações que removem campos, mudam significados ou quebram clientes precisam de planejamento, período de transição e comunicação.

Algumas APIs colocam a versão na URL, como /api/v1/clientes. Outras usam cabeçalhos ou tipos de mídia. O mais importante é ter uma política consistente e um processo de descontinuação.

O OpenAPI pode documentar endpoints, parâmetros, esquemas e respostas em um formato que ferramentas conseguem processar. A documentação não substitui testes de contrato, mas facilita integração e geração de clientes.

REST vs GraphQL, gRPC e SOAP

Nenhuma abordagem é sempre mais rápida, segura ou escalável. O resultado depende do contrato, implementação, infraestrutura, carga, ferramentas e experiência da equipe. Veja também o que é GraphQL.

Erros comuns em APIs REST

• usar GET para alterar ou excluir dados;
• tratar PUT e PATCH como sinônimos sem definir a semântica;
• retornar status 200 em erros;
• criar URLs com verbos para cada ação simples;
• enviar listas sem paginação;
• ignorar concorrência ao atualizar recursos;
• expor mensagens internas e stack traces;
• confundir autenticação com autorização;
• criar versões sem uma política de compatibilidade.

Perguntas frequentes

REST exige JSON?

Não. Uma representação pode usar JSON, HTML, XML, texto, imagem ou outro formato. JSON é comum por ser bem suportado em aplicações web.

Qual é a diferença entre PUT e PATCH?

PUT representa a criação ou substituição completa do estado do recurso no endereço informado. PATCH aplica um conjunto de alterações parciais conforme o formato aceito pela API.

Uma API stateless pode usar login?

Sim. Cada requisição pode enviar um cookie ou token que permita identificar o cliente. O servidor não deve depender de um contexto de aplicação oculto de requisições anteriores para interpretar a atual.

Endpoint e URL são a mesma coisa?

Endpoint costuma significar a combinação de método e endereço que oferece uma operação, como GET /api/clientes/42. A mesma URL pode aceitar métodos diferentes.

REST é adequado para microsserviços?

Pode ser, especialmente quando interoperabilidade e semântica HTTP são importantes. Para comunicação interna de baixa latência, contratos tipados ou streaming, gRPC e mensageria também podem ser considerados.

Fontes e verificação

Conteúdo revisado em 17 de julho de 2026 com base na dissertação original de Roy Fielding, no RFC 9110 sobre semântica HTTP, no RFC 5789 sobre o método PATCH e na especificação OpenAPI.

Conclusão

Uma API REST bem projetada usa recursos claros, métodos HTTP com a semântica correta, códigos de resposta úteis e um contrato consistente. Ela também precisa de validação, autorização, paginação, controle de concorrência, documentação e monitoramento.

O objetivo não é apenas criar endpoints que retornam JSON. É permitir que clientes diferentes interajam com o sistema de forma previsível, segura e evolutiva.