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:

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:

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:

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:

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:

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:

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:

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:

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