REST (Representational State Transfer) é um conjunto de princípios para construir APIs web usando HTTP. Uma API RESTful usa URLs para identificar recursos, métodos HTTP para definir ações, JSON para trocar dados e códigos de status para comunicar resultados — tudo de forma simples, previsível e fácil de documentar.
Você já usou um aplicativo de previsão do tempo? Ou fez login com o Google em algum site? Então você já usou uma API — provavelmente RESTful. Mas o que acontece por trás disso tudo? E como construir e documentar sua própria API?
Neste guia, você vai sair do zero até conseguir entender, criar e documentar uma API REST do jeito certo. Sem jargões desnecessários. Com exemplos reais e práticos.
01 O que é uma API?
API significa
Application Programming Interface — Interface de Programação de Aplicações. É um jeito padronizado de dois sistemas conversarem entre si.
Pensa assim: quando você vai a um restaurante, não entra na cozinha para pegar sua comida. Você fala com o garçom, ele leva o pedido para a cozinha e traz o resultado para você. A API funciona exatamente como esse garçom — ela recebe seu pedido, faz a comunicação com o sistema por trás e te devolve uma resposta.
Quando um app de clima mostra a temperatura da sua cidade, ele está fazendo uma chamada de API para buscar esses dados em algum servidor remoto. E é isso que acontece em praticamente todo aplicativo moderno.
02 O que é REST?
REST significa Representational State Transfer — Transferência de Estado Representacional. É um conjunto de regras criado em 2000 pelo cientista Roy Fielding para definir como APIs devem funcionar na web.
Não é uma tecnologia nem um framework. É um estilo arquitetural — boas práticas que, quando seguidas, tornam a API mais simples, previsível e fácil de usar. Quando uma API segue essas regras, ela é chamada de RESTful.
03 Os 6 princípios do REST
Para uma API ser considerada RESTful, ela precisa respeitar seis princípios fundamentais:
Princípio 01
Interface uniforme
Todos os recursos são acessados da mesma forma, com uma estrutura previsível de URLs e métodos. Isso facilita a vida de quem vai usar a API.
Princípio 02
Cliente-servidor
O cliente (quem faz o pedido) e o servidor (quem responde) são independentes. Um não precisa saber como o outro funciona por dentro.
Princípio 03
Sem estado (Stateless)
Cada requisição deve conter todas as informações necessárias para ser processada. O servidor não guarda informações sobre requisições anteriores. Afinal, isso torna o sistema mais escalável e previsível.
Princípio 04
Cache
As respostas podem ser armazenadas em cache para melhorar o desempenho. O servidor deve indicar se uma resposta pode ou não ser cacheada.
Princípio 05
Sistema em camadas
O cliente não precisa saber se está falando diretamente com o servidor final ou com algum intermediário, como um balanceador de carga ou gateway.
Princípio 06 — Opcional
Código sob demanda
O servidor pode enviar código executável para o cliente, como scripts JavaScript. Esse é o único princípio opcional do REST.
04 Os métodos HTTP
APIs RESTful funcionam sobre o protocolo HTTP — o mesmo que seu navegador usa para carregar páginas web. Cada ação usa um método específico:
GET
Buscar dados
Listar ou retornar recursos. Nunca modifica dados.
POST
Criar recurso
Cria um novo registro no servidor.
PUT
Atualizar tudo
Substitui um recurso por completo.
PATCH
Atualizar parcial
Atualiza apenas alguns campos do recurso.
DELETE
Remover recurso
Exclui um registro do servidor.
05 Recursos e endpoints
No REST, tudo é um recurso. Um usuário é um recurso. Um produto é um recurso. Um pedido é um recurso. Cada recurso tem uma URL única — chamada de endpoint.
endpoints
GET /usuarios → lista todos os usuários
GET /usuarios/42 → retorna o usuário de ID 42
POST /usuarios → cria um novo usuário
PUT /usuarios/42 → atualiza todos os dados do usuário 42
PATCH /usuarios/42 → atualiza parte dos dados do usuário 42
DELETE /usuarios/42 → remove o usuário 42
✓
A URL representa o quê você quer acessar. O método HTTP representa o que você quer fazer com ele. Essa separação é o coração do REST.
06 Códigos de resposta HTTP
Toda resposta de uma API REST vem acompanhada de um código de status HTTP, indicando se a requisição funcionou e por quê. Os mais importantes:
200OKTudo funcionou como esperado.
201CreatedRecurso criado com sucesso.
204No ContentSucesso, sem conteúdo para retornar.
400Bad RequestDados inválidos ou malformados.
401UnauthorizedSem autenticação válida.
403ForbiddenAutenticado, mas sem permissão.
404Not FoundRecurso não existe.
500Server ErrorErro interno no servidor.
07 O formato JSON
A grande maioria das APIs RESTful usa JSON (JavaScript Object Notation) para trocar dados. É um formato leve, legível e fácil de processar por qualquer linguagem de programação.
Resposta de GET /usuarios/42
JSON · resposta
{
"id": 42,
"nome": "Maria Silva",
"email": "maria@email.com",
"ativo": true,
"criado_em": "2026-01-15"
}
Corpo de requisição ao criar um usuário com POST /usuarios
JSON · requisição
{
"nome": "João Souza",
"email": "joao@email.com",
"senha": "minhasenha123"
}
08 Exemplo completo: API de tarefas
Imagine uma API simples para gerenciar tarefas (to-do list). Veja como ficaria a estrutura completa:
estrutura de endpoints
Base URL: https://api.minhaapp.com/v1
GET /tarefas → lista todas as tarefas
GET /tarefas/5 → retorna a tarefa de ID 5
POST /tarefas → cria uma nova tarefa
PATCH /tarefas/5 → marca a tarefa 5 como concluída
DELETE /tarefas/5 → remove a tarefa 5
resposta · GET /tarefas
[
{ "id": 1, "titulo" "Estudar REST APIs", "concluida": false },
{ "id": 2, "titulo" "Fazer exercícios", "concluida": true }
]
09 Como documentar uma API REST
Documentar uma API é tão importante quanto construí-la. Sem documentação, ninguém sabe como usar o que você criou. Uma boa documentação precisa ter:
Checklist de documentação completa
- Descrição geral — o que a API faz e para quem é
- URL base — o endereço raiz de todos os endpoints
- Autenticação — como o usuário se autentica (token, chave, OAuth etc.)
- Lista de endpoints com métodos e parâmetros
- Exemplos reais de requisição e resposta em JSON
- Tabela de códigos de erro e o que cada um significa
Exemplo de documentação de endpoint
POST
/usuarios
Cria um novo usuário na plataforma. Requer autenticação via token Bearer.
Headers
Authorization: Bearer {seu_token}
Content-Type: application/json
Corpo da requisição
{
"nome": "string (obrigatório)",
"email": "string (obrigatório)",
"senha": "string (obrigatório, mín. 8 caracteres)"
}
Resposta de sucesso — 201 Created
{
"id": 99,
"nome": "João Souza",
"email": "joao@email.com",
"criado_em": "2026-04-25"
}
Possíveis erros
| Código | Motivo |
|---|
| 400 | Dados inválidos ou campos obrigatórios ausentes |
| 409 | E-mail já cadastrado |
| 500 | Erro interno do servidor |
10 Ferramentas para documentar APIs
Você não precisa escrever a documentação na mão. Existem ferramentas excelentes para isso:
11 Boas práticas para nomear endpoints
Alguns erros são muito comuns entre iniciantes. Vale fixar essas regras:
-
✓
Use substantivos, não verbos
O método HTTP já indica a ação. Use GET /produtos em vez de GET /buscarProdutos
-
✓
Use letras minúsculas e hífens
Prefira /pedidos-pendentes em vez de /PedidosPendentes
-
✓
Use plural para coleções
/usuarios é mais correto que /usuario
-
✓
Versione sua API desde o início
Sempre use /v1/usuarios — isso evita quebrar clientes quando você atualizar a API
-
✗
Nunca exponha detalhes internos nas URLs
Evite caminhos como /api/mysql/tabela_usuarios
Perguntas frequentes
Qual a diferença entre REST e RESTful?
REST é o conjunto de princípios. RESTful é o adjetivo usado para descrever uma API que segue esses princípios. Na prática, os termos são usados de forma intercambiável no mercado.
REST e HTTP são a mesma coisa?
Não. REST é um estilo arquitetural que usa o HTTP. Teoricamente o REST poderia funcionar sobre outros protocolos, mas na prática ele sempre é implementado sobre HTTP.
Qual a diferença entre PUT e PATCH?
O PUT substitui o recurso por completo — você precisa enviar todos os campos, mesmo os que não mudaram. O PATCH atualiza apenas os campos enviados. Na maioria dos casos, o PATCH é mais eficiente e é o mais recomendado para atualizações parciais.
Por onde começar a praticar?
Instale o Postman ou o Insomnia e faça chamadas para APIs públicas e gratuitas, como o ViaCEP (viacep.com.br), a API do GitHub (api.github.com) ou o JSONPlaceholder (jsonplaceholder.typicode.com). Observe os métodos, os status codes e os JSONs de resposta. Em poucos minutos tudo vai fazer muito mais sentido.
Ficou com alguma dúvida sobre REST ou RESTful APIs? Deixe seu comentário abaixo — a gente responde e ajuda você a avançar no tema.
