API REST é o padrão dominante de comunicação entre sistemas na web: é assim que seu front-end conversa com o back-end, que seu ERP consulta um CNPJ e que seu e-commerce calcula frete. Mesmo assim, boa parte dos devs usa REST todos os dias sem saber o que a sigla exige de verdade, e a confusão entre “REST” e “RESTful” segue viva nas entrevistas. Este guia explica os princípios da arquitetura, os métodos HTTP e status codes que importam, e mostra exemplos reais de requisição e resposta.
O que é uma API REST?
API REST é uma interface de comunicação entre sistemas que segue o estilo arquitetural REST (Representational State Transfer): os dados são expostos como recursos identificados por URLs, manipulados pelos métodos do protocolo HTTP (GET, POST, PUT, DELETE) e transferidos em formato padronizado, quase sempre JSON.
REST não é um protocolo nem uma biblioteca: é um conjunto de princípios descrito por Roy Fielding em sua tese de doutorado, em 2000. Fielding foi um dos autores da especificação do HTTP, e o REST nasceu como uma forma de aproveitar o que o protocolo já oferece (métodos, status codes, cache) em vez de reinventar tudo por cima, como o SOAP fazia com seus envelopes XML.
Os 6 princípios da arquitetura REST
Pra uma API ser REST de verdade, Fielding definiu seis restrições (constraints). Na prática, são elas que diferenciam uma API bem desenhada de “um endpoint que retorna JSON”:
- Cliente-servidor: front-end e back-end evoluem de forma independente. O cliente não sabe como o dado é armazenado; o servidor não sabe como ele é exibido.
- Stateless: cada requisição carrega tudo que o servidor precisa pra respondê-la (token de autenticação incluso). O servidor não guarda sessão entre chamadas, o que permite escalar horizontalmente sem afinidade de servidor.
- Cacheável: as respostas declaram se podem ser cacheadas e por quanto tempo (headers
Cache-Control,ETag). Um GET de CEP, por exemplo, pode viver horas em cache sem prejuízo. - Interface uniforme: recursos identificados por URI, manipulados por representações (JSON), com mensagens autodescritivas. É o princípio que torna qualquer API REST familiar pra quem nunca a viu.
- Sistema em camadas: o cliente não precisa saber se fala com o servidor final, um load balancer ou um gateway. Camadas intermediárias (proxy, CDN, cache) entram sem quebrar o contrato.
- Code on demand (opcional): o servidor pode enviar código executável ao cliente. É a única restrição opcional e raramente usada em APIs de dados.
Como funciona uma API REST na prática
Recursos e URIs
Em REST, tudo é recurso: cliente, pedido, produto. Cada recurso tem um identificador único (URI), e a hierarquia das URLs expressa a relação entre eles. A convenção: substantivos no plural, sem verbos (o verbo é o método HTTP):
GET /clientes → lista clientes
GET /clientes/42 → detalha o cliente 42
POST /clientes → cria um cliente
PUT /clientes/42 → substitui o cliente 42
DELETE /clientes/42 → remove o cliente 42
GET /clientes/42/pedidos → pedidos do cliente 42
Métodos HTTP: o verbo da operação
| Método | Ação | Idempotente | Tem corpo? |
|---|---|---|---|
| GET | ler recurso | ✅ | não |
| POST | criar recurso | ❌ | sim |
| PUT | substituir recurso inteiro | ✅ | sim |
| PATCH | atualizar parte do recurso | depende | sim |
| DELETE | remover recurso | ✅ | raramente |
A coluna de idempotência importa mais do que parece: ela define o que é seguro repetir quando a rede falha. O tema rende guia próprio: veja idempotência em APIs.
Status codes que todo dev precisa conhecer
| Código | Significado | Quando usar |
|---|---|---|
| 200 | OK | leitura ou atualização bem-sucedida |
| 201 | Created | recurso criado via POST |
| 204 | No Content | sucesso sem corpo (DELETE) |
| 400 | Bad Request | payload inválido ou malformado |
| 401 | Unauthorized | sem autenticação válida |
| 403 | Forbidden | autenticado, mas sem permissão |
| 404 | Not Found | recurso não existe |
| 409 | Conflict | conflito de estado (registro duplicado) |
| 422 | Unprocessable Entity | sintaxe ok, validação de negócio falhou |
| 429 | Too Many Requests | rate limit excedido |
| 500 | Internal Server Error | erro não tratado no servidor |
A lista completa, com os detalhes de cada família, está no nosso guia de HTTP status codes.
Exemplo real de requisição e resposta
Uma consulta de CNPJ numa API REST típica:
curl -X GET "https://api.exemplo.com.br/v2/cnpj/19131243000197" \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Accept: application/json"HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=86400
{
"cnpj": "19131243000197",
"razao_social": "OPEN KNOWLEDGE BRASIL",
"situacao_cadastral": "ATIVA",
"cnae_principal": { "codigo": "9430-8/00", "descricao": "Atividades de associações..." }
}Repare nos princípios em ação: a URL identifica o recurso (CNPJ específico), o método expressa a intenção (GET = leitura), a resposta declara o formato (Content-Type) e a política de cache (Cache-Control), e a autenticação viaja na própria requisição (stateless).
API REST vs RESTful: qual a diferença?
REST é o estilo arquitetural; RESTful é o adjetivo pra APIs que o seguem. Na prática, os termos viraram sinônimos, e a distinção que sobreviveu é de grau: uma API “RESTful de verdade” cumpre as seis restrições, enquanto muita API por aí usa HTTP e JSON mas guarda estado de sessão, ignora cache e trata tudo como POST. Funciona? Funciona. É REST? Tecnicamente não. Em entrevista, responda assim: REST é a especificação, RESTful é a implementação que a respeita.
Boas práticas de design de API REST
Versionamento
Toda API muda. Versionar desde o primeiro dia evita quebrar clientes em produção. As duas abordagens comuns: versão na URI (/v2/clientes, mais visível e fácil de rotear) ou no header (Accept: application/vnd.api.v2+json, mais “pura” e menos adotada). A versão na URI domina o mercado por simplicidade.
Autenticação
Os três modelos mais comuns, do mais simples ao mais completo: API key (um token fixo no header, padrão em APIs de consulta), JWT (token assinado com expiração, padrão em aplicações com login) e OAuth2 (delegação de acesso entre serviços, padrão em integrações com terceiros). Em todos os casos, a credencial viaja em header, nunca na URL, porque URLs param em logs.
HATEOAS: links na resposta
HATEOAS (Hypermedia as the Engine of Application State) é a parte do REST que quase ninguém implementa: a resposta inclui links pras ações possíveis a partir dali, e o cliente navega pela API como navega por páginas web:
{
"id": 42,
"status": "aguardando_pagamento",
"_links": {
"self": { "href": "/pedidos/42" },
"pagar": { "href": "/pedidos/42/pagamento", "method": "POST" },
"cancelar": { "href": "/pedidos/42", "method": "DELETE" }
}
}Vale a pena? Pra APIs públicas com muitos consumidores, sim: o cliente descobre capacidades sem ler changelog. Pra APIs internas, a maioria dos times pula essa restrição e documenta no OpenAPI.
REST vs SOAP vs GraphQL vs gRPC
| Critério | REST | SOAP | GraphQL | gRPC |
|---|---|---|---|---|
| Formato | JSON (livre) | XML (rígido) | JSON (schema) | Protobuf (binário) |
| Transporte | HTTP/1.1+ | HTTP, SMTP | HTTP (POST único) | HTTP/2 |
| Busca de dados | endpoints fixos | operações fixas | cliente escolhe campos | métodos tipados |
| Cache HTTP | nativo | difícil | limitado | não |
| Melhor pra | APIs públicas e CRUD | legado corporativo | front-ends com telas variadas | microsserviços internos |
REST continua sendo o padrão de fato pra APIs públicas: tem o menor atrito de adoção (qualquer linguagem fala HTTP e JSON), aproveita o cache da web e qualquer dev sabe consumi-lo. GraphQL e gRPC resolvem dores específicas (over-fetching e performance interna, respectivamente), não substituem REST como interface universal.
Perguntas frequentes
O que é uma API REST?
É uma interface de comunicação entre sistemas que expõe dados como recursos acessíveis por URLs e manipulados via métodos HTTP (GET, POST, PUT, DELETE), com respostas geralmente em JSON. Segue os princípios do estilo arquitetural REST, definido por Roy Fielding em 2000.
Como funciona uma API REST?
O cliente envia uma requisição HTTP indicando o recurso (URL), a operação (método) e, quando necessário, os dados (corpo em JSON) e a autenticação (header). O servidor processa e devolve um status code indicando o resultado e o recurso solicitado no corpo da resposta.
Qual a diferença entre API REST e RESTful?
REST é o conjunto de princípios arquiteturais; RESTful descreve a API que os implementa. No uso cotidiano os termos são intercambiáveis, mas a rigor uma API só é RESTful quando cumpre as seis restrições do REST, incluindo stateless e interface uniforme.
Quais são os tipos de API?
Pela arquitetura, os principais estilos são REST, SOAP, GraphQL e gRPC. Pelo acesso, as APIs se dividem em públicas (abertas a qualquer dev), parceiras (acesso mediante contrato) e privadas (uso interno da empresa).
Qual um exemplo de API REST?
As APIs de consulta de dados brasileiras são exemplos clássicos: você faz um GET em /cnpj/{numero} ou /cep/{numero} com seu token no header e recebe os dados em JSON. As APIs do GitHub, Stripe e Mercado Pago seguem o mesmo modelo.
Conclusão
REST venceu porque aposta no que a web já sabe fazer: URLs identificam coisas, métodos HTTP expressam intenção, status codes comunicam resultado e o cache funciona de graça. Dominar esses fundamentos (recursos bem modelados, métodos e códigos corretos, stateless de verdade) vale mais do que decorar frameworks, porque é o contrato que todas as APIs que você vai consumir e construir têm em comum. Se quiser ver os princípios aplicados, as APIs de consulta do Hub do Desenvolvedor são um bom laboratório: REST puro, com token no header e JSON na resposta.
