O que é REST? Arquitetura de APIs explicada

REST é o estilo de arquitetura por trás da maioria das APIs web que você usa e constrói. Mas, apesar de onipresente, o termo é frequentemente mal compreendido — muita gente chama de "REST" qualquer API que devolve JSON. Neste artigo vamos esclarecer o que REST realmente é, quais princípios o definem e como reconhecer (e construir) uma API verdadeiramente RESTful.

A origem do termo

REST significa Representational State Transfer, ou Transferência de Estado Representacional. O termo foi cunhado por Roy T. Fielding (2000) em sua tese de doutorado na Universidade da Califórnia, Irvine. Fielding, que também ajudou a projetar o protocolo HTTP, não inventou uma tecnologia nova: ele descreveu o conjunto de restrições arquiteturais que já tornavam a web tão escalável e robusta.

Em outras palavras, REST é um estilo arquitetural — um conjunto de princípios — e não um protocolo ou um padrão rígido. Uma API que segue esses princípios é chamada de RESTful. Antes de seguir, se você ainda não tem clareza do conceito mais amplo, vale ler O que é uma API? Definição clara para iniciantes.

É útil entender o contexto histórico. No início dos anos 2000, o padrão dominante para integração entre sistemas era o SOAP, um protocolo pesado baseado em XML, com envelopes verbosos e contratos formais (WSDL). REST surgiu como uma alternativa que abraçava a simplicidade da própria web: usar o HTTP como ele já era, sem reinventar a roda. Essa aposta na simplicidade venceu — hoje a esmagadora maioria das APIs públicas é RESTful ou inspirada em REST.

As seis restrições do REST

Fielding (2000) definiu seis restrições. Uma API só é genuinamente RESTful quando respeita todas elas:

• Cliente-servidor: a interface do usuário e o armazenamento de dados são separados, evoluindo de forma independente.
• Sem estado (stateless): cada requisição contém tudo o que o servidor precisa para entendê-la; o servidor não guarda contexto entre chamadas.
• Cacheável: as respostas devem indicar se podem ser armazenadas em cache, melhorando a performance.
• Interface uniforme: o coração do REST — uma forma padronizada de identificar e manipular recursos.
• Sistema em camadas: pode haver intermediários (proxies, balanceadores) sem que o cliente perceba.
• Código sob demanda (opcional): o servidor pode enviar código executável ao cliente, como JavaScript.

Dessas, duas merecem atenção especial: o stateless e a interface uniforme. As outras quatro, embora importantes, são frequentemente herdadas "de graça" quando você usa HTTP corretamente. A interface uniforme, em particular, é o que Fielding considera a característica central que distingue REST de outros estilos arquiteturais.

Recursos: o substantivo central

Em REST, tudo gira em torno de recursos. Um recurso é qualquer coisa nomeável: um usuário, um produto, um pedido, uma foto. Cada recurso tem um identificador único — uma URL.

A boa prática é nomear recursos com substantivos no plural, não verbos:

GET  /usuarios          → lista de usuários
GET  /usuarios/42       → o usuário de id 42
POST /usuarios          → cria um novo usuário

Repare que a URL nunca contém o verbo "criar" ou "buscar". Quem expressa a ação é o método HTTP, não a URL. Esse é um erro clássico de quem acha que está fazendo REST: criar endpoints como /criarUsuario ou /buscarPedidos.

Recursos aninhados e relacionamentos

Recursos frequentemente têm relações entre si, e a URL pode expressá-las de forma hierárquica:

GET  /usuarios/42/pedidos        → pedidos do usuário 42
GET  /usuarios/42/pedidos/7      → pedido 7 daquele usuário
POST /usuarios/42/pedidos        → cria um pedido para o usuário 42

O bom senso aqui é não aninhar demais. Caminhos com mais de dois níveis (/a/1/b/2/c/3) ficam difíceis de ler e manter. Quando o aninhamento profundo é necessário, costuma ser melhor expor o recurso de nível mais baixo diretamente, com filtros via query string: GET /pedidos?usuario=42.

Filtragem, ordenação e paginação

Listas de recursos raramente devem retornar tudo de uma vez. Convenções comuns usam a query string, que não faz parte da identidade do recurso, mas modula a representação retornada:

GET /produtos?categoria=livros&ordenar=preco&pagina=2&limite=20

Paginação é especialmente importante: devolver dez mil registros numa única resposta sobrecarrega servidor e cliente. As duas estratégias mais comuns são por offset (pagina e limite) e por cursor (um ponteiro opaco para a próxima página), sendo a segunda mais robusta quando os dados mudam durante a navegação.

Os métodos HTTP como verbos

A interface uniforme do REST usa os métodos do HTTP para definir a ação sobre o recurso. Esse mapeamento é o que dá previsibilidade à API:

• GET: lê um recurso, sem causar efeitos colaterais.
• POST: cria um novo recurso.
• PUT: substitui completamente um recurso existente.
• PATCH: atualiza parcialmente um recurso.
• DELETE: remove um recurso.

A semântica desses métodos é padronizada pela RFC 9110: HTTP Semantics (Fielding, Nottingham, Reschke, 2022). Conceitos importantes vêm de lá, como idempotência: chamar DELETE /usuarios/42 várias vezes tem o mesmo efeito de chamar uma vez, enquanto POST repetido cria vários recursos. Como REST se apoia tão fortemente no HTTP, vale entender bem o protocolo em O que é HTTP? Métodos, status e como a web conversa.

Idempotência e segurança: por que importam

Dois conceitos da RFC 9110 organizam o comportamento esperado:

• Um método é seguro (safe) se não altera o estado do servidor. GET, HEAD e OPTIONS são seguros. Por isso é grave usar GET para deletar algo: navegadores, crawlers e proxies assumem que podem chamar GET livremente.
• Um método é idempotente se chamá-lo N vezes tem o mesmo efeito de chamá-lo uma vez. GET, PUT, DELETE são idempotentes; POST não é.

A tabela abaixo resume:

| Método | Seguro | Idempotente | Uso típico | |--------|--------|-------------|------------| | GET | Sim | Sim | Ler recurso | | POST | Não | Não | Criar recurso | | PUT | Não | Sim | Substituir recurso | | PATCH | Não | Não (em geral) | Atualizar parte | | DELETE | Não | Sim | Remover recurso |

Essa propriedade tem valor prático: clientes podem reenviar com segurança requisições idempotentes que falharam por timeout de rede, sem medo de duplicar efeitos. É a base para mecanismos de retry confiáveis.

Representações: REST e JSON

O "R" de "Representational" indica que o cliente nunca acessa o recurso diretamente — ele recebe uma representação dele. O mesmo recurso "usuário 42" pode ser representado em JSON, XML ou outro formato. Na prática, hoje a representação quase sempre é JSON.

{
  "id": 42,
  "nome": "Bruno Lima",
  "email": "bruno@exemplo.com",
  "ativo": true
}

O cliente recebe essa representação, eventualmente a modifica e a envia de volta para alterar o estado no servidor — daí "transferência de estado". Para dominar o formato, veja O que é JSON? O formato de dados da web.

O cliente e o servidor negociam o formato por meio de cabeçalhos. O cliente envia Accept: application/json para dizer o que aceita, e o servidor responde com Content-Type: application/json para informar o que está enviando. Esse mecanismo, chamado negociação de conteúdo, permite que o mesmo endpoint sirva JSON para uma aplicação e CSV para outra, sem mudar a URL.

Códigos de status: a resposta fala

Uma API RESTful usa os códigos de status HTTP para comunicar o resultado de cada operação, em vez de inventar campos próprios de erro. Os mais comuns:

• 2xx — sucesso: 200 OK, 201 Created, 204 No Content.
• 3xx — redirecionamento: 301 Moved Permanently, 304 Not Modified.
• 4xx — erro do cliente: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests.
• 5xx — erro do servidor: 500 Internal Server Error, 503 Service Unavailable.

Usar esses códigos corretamente faz a API ser previsível e fácil de depurar. Um cliente que recebe 404 sabe imediatamente que o recurso não existe, sem precisar interpretar mensagens livres.

Alguns acertos finos fazem diferença: responder 201 Created ao criar um recurso, idealmente com um cabeçalho Location apontando para a URL do novo recurso; usar 204 No Content quando a operação teve sucesso mas não há corpo a retornar (típico de DELETE); e distinguir 401 (não autenticado — você não provou quem é) de 403 (autenticado mas não autorizado — você é conhecido, mas não tem permissão). Essa distinção conecta-se diretamente com Autenticação vs autorização: qual a diferença?.

Stateless: por que importa tanto

A restrição sem estado significa que o servidor não mantém uma "sessão" na memória entre requisições. Cada chamada precisa carregar suas próprias credenciais e parâmetros. Isso parece custoso, mas tem um ganho gigante: escalabilidade.

Como nenhuma requisição depende de um servidor específico, você pode colocar dezenas de servidores atrás de um balanceador de carga, e qualquer um deles atende qualquer requisição. Esse é exatamente o tipo de propriedade que viabiliza arquiteturas de microsserviços, em que serviços independentes escalam de forma autônoma.

Vale desfazer uma confusão comum: stateless não significa que a aplicação não tem estado. O estado dos dados (usuários, pedidos) continua existindo — ele mora no banco de dados. O que é stateless é a conexão: o servidor não guarda quem você é entre uma requisição e outra. Por isso cada chamada reapresenta seu token de autenticação. O preço a pagar é que cada requisição fica um pouco maior (carrega credenciais e contexto), mas o benefício de poder escalar horizontalmente sem "afinidade de sessão" compensa largamente na maioria dos sistemas.

REST e cache

A restrição cacheável é frequentemente subaproveitada. O HTTP oferece um mecanismo de cache rico, controlado por cabeçalhos como Cache-Control, ETag e Last-Modified. Um servidor pode marcar uma resposta como cacheável por um tempo, e o cliente — ou um proxy intermediário — reutiliza a resposta sem nem chamar o servidor de novo.

O fluxo de validação condicional é elegante: o servidor envia um ETag (uma espécie de impressão digital da representação); na próxima vez, o cliente envia If-None-Match com aquele valor; se nada mudou, o servidor responde 304 Not Modified sem corpo, economizando banda. Aproveitar bem o cache HTTP é uma das maneiras mais baratas de melhorar performance de uma API REST.

REST e segurança

Ser stateless não significa ser inseguro. Como cada requisição é autônoma, ela precisa carregar sua própria prova de identidade — normalmente um token enviado em um cabeçalho. Proteger esses endpoints envolve HTTPS obrigatório, validação rigorosa de entrada, controle de acesso por recurso e limitação de taxa. Esse conjunto de práticas é detalhado em Segurança de APIs: protegendo seus endpoints.

Um cuidado específico do estilo RESTful é a vulnerabilidade conhecida como IDOR (referência insegura direta a objeto): como recursos são identificados por URLs previsíveis (/usuarios/42), o servidor precisa sempre verificar se o solicitante tem permissão sobre aquele recurso específico, e não apenas se está autenticado. Confiar no fato de que o cliente "não conhece" a URL de outro usuário é uma falha grave.

Versionamento de APIs

APIs evoluem, e mudanças incompatíveis quebram clientes existentes. O versionamento administra essa evolução. As abordagens mais comuns são:

• Na URL: /v1/usuarios, /v2/usuarios. Simples e explícito, é o mais difundido na prática.
• Em cabeçalho: o cliente envia Accept: application/vnd.minhaapi.v2+json. Mais "puro" em termos REST, mas menos visível e mais difícil de testar no navegador.

Não há consenso universal, mas a regra que importa é: nunca quebre clientes existentes sem aviso. Sempre que possível, prefira mudanças aditivas (novos campos opcionais não quebram ninguém) a mudanças destrutivas.

Tratamento de erros que ajuda o cliente

Devolver o código de status certo é o começo, mas uma API madura também explica o erro no corpo da resposta, de forma estruturada e consistente. Comparar um erro inútil com um erro útil deixa a diferença clara:

// Pouco útil: o cliente recebe 400 e fica adivinhando
{ "erro": true }

// Útil: o cliente sabe exatamente o que corrigir
{
  "tipo": "validacao",
  "mensagem": "O campo 'email' é obrigatório e deve ter formato válido.",
  "campos": [
    { "campo": "email", "problema": "formato_invalido" }
  ]
}

Existe até um padrão consolidado para isso, a RFC 9457 (Problem Details for HTTP APIs), que define um corpo JSON com campos como type, title, status e detail. Adotar um formato de erro único em toda a API poupa horas de depuração de quem a consome, porque o cliente pode tratar erros de forma genérica em vez de interpretar mensagens livres caso a caso.

REST e suas alternativas

REST não é a única forma de construir APIs, e conhecer as alternativas ajuda a entender suas forças:

• GraphQL dá ao cliente uma única URL e uma linguagem de consulta para pedir exatamente os campos que quer, resolvendo o problema de over-fetching (receber dados demais) e under-fetching (precisar de várias chamadas). Em troca, perde a simplicidade do cache HTTP.
• gRPC usa HTTP/2 e formato binário, sendo muito eficiente em comunicação serviço-a-serviço, ao custo de não ser legível por humanos nem facilmente testável no navegador.

REST continua dominante em APIs públicas justamente por ser simples, baseado em padrões universais e fácil de consumir com nada além de um cliente HTTP comum.

O modelo de maturidade de Richardson

Uma forma popular de avaliar o quão RESTful uma API realmente é vem do Modelo de Maturidade de Richardson, que descreve quatro níveis:

• Nível 0 — o pântano do POX: uma única URL e um único método (geralmente POST) para tudo. É basicamente RPC sobre HTTP; o HTTP serve apenas de túnel.
• Nível 1 — recursos: a API passa a ter várias URLs, uma por recurso, mas ainda usa poucos métodos. Já é um avanço de organização.
• Nível 2 — verbos HTTP: a API usa os métodos (GET, POST, PUT, DELETE) com sua semântica correta e responde com códigos de status apropriados. É aqui que vive a esmagadora maioria das APIs chamadas de "RESTful" na prática.
• Nível 3 — HATEOAS: as respostas incluem links para as próximas ações possíveis, tornando a API autodescritiva e navegável. É o nível que Fielding considera o REST "completo", e o mais raro de encontrar.

O modelo é útil porque dá vocabulário para uma conversa honesta: a maior parte do mercado vive confortavelmente no nível 2, e está tudo bem. Saber disso evita tanto o purismo paralisante quanto a ilusão de que devolver JSON já é REST.

Erros comuns que quebram o "RESTful"

Muita API se diz REST mas viola os princípios. Fique atento a estes sinais:

• Verbos na URL: /getUsuario/42 em vez de GET /usuarios/42.
• Usar sempre 200: devolver 200 OK mesmo em erros, escondendo a falha num campo do JSON.
• Ignorar idempotência: usar GET para alterar dados ou POST para tudo.
• Estado no servidor: depender de sessão em memória, quebrando a escalabilidade.
• Ignorar paginação: devolver coleções gigantes inteiras numa só resposta.
• Mensagens de erro inúteis: um 400 sem corpo explicando o que está errado força o cliente a adivinhar.

Evitar esses erros é o que separa uma API que apenas "fala JSON" de uma API genuinamente RESTful.

Perguntas frequentes

Toda API que devolve JSON é REST? Não. JSON é apenas um formato de representação. Uma API só é RESTful se respeita as restrições — sobretudo recursos identificados por URL, métodos HTTP como verbos, ausência de estado de sessão e uso correto de códigos de status.

Preciso implementar HATEOAS para ser REST? HATEOAS (incluir na resposta links para as próximas ações possíveis) é, segundo Fielding, parte essencial da interface uniforme. Na prática, pouquíssimas APIs "RESTful" o implementam por completo. A maioria fica num nível pragmático de REST sem HATEOAS — funcional, ainda que não 100% fiel à definição original.

PUT ou PATCH para atualizar? Use PUT quando o cliente envia a representação completa do recurso (substituição total) e PATCH quando envia apenas os campos a alterar. PUT é idempotente; PATCH, em geral, não.

REST e RESTful são a mesma coisa? REST é o estilo arquitetural (o conjunto de princípios); RESTful é o adjetivo que descreve uma API que segue esses princípios.

Conclusão

REST não é uma tecnologia que você instala, mas uma forma disciplinada de projetar APIs em torno de recursos, métodos HTTP e respostas sem estado. Quando bem aplicado, gera APIs previsíveis, escaláveis e fáceis de consumir — exatamente as qualidades que Fielding (2000) buscava ao descrever a arquitetura da própria web. Dominar esses princípios — recursos como substantivos, métodos como verbos, códigos de status que falam, ausência de estado e bom uso de cache — é essencial para qualquer desenvolvedor que constrói sistemas conectados.

Referências

• Roy T. Fielding (2000). Architectural Styles and the Design of Network-based Software Architectures. PhD Dissertation, UC Irvine.
• Fielding, Nottingham, Reschke (2022). RFC 9110: HTTP Semantics. IETF.
• Nottingham, Wilde, Dalal (2023). RFC 9457: Problem Details for HTTP APIs. IETF.
• Leonard Richardson, Sam Ruby (2007). RESTful Web Services. O'Reilly Media.
• Mark Masse (2011). REST API Design Rulebook. O'Reilly Media.