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.
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.
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.
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.
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:
Buscar dados
Listar ou retornar recursos. Nunca modifica dados.
Criar recurso
Cria um novo registro no servidor.
Atualizar tudo
Substitui um recurso por completo.
Atualizar parcial
Atualiza apenas alguns campos do recurso.
Remover recurso
Exclui um registro do servidor.
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.
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.
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:
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:
{
"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:
{
"nome": "João Souza",
"email": "joao@email.com",
"senha": "minhasenha123"
}
Exemplo completo: API de tarefas
Imagine uma API simples para gerenciar tarefas (to-do list). Veja como ficaria a estrutura completa:
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
[
{ "id": 1, "titulo": "Estudar REST APIs", "concluida": false },
{ "id": 2, "titulo": "Fazer exercícios", "concluida": true }
]
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
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 |
Ferramentas para documentar APIs
Você não precisa escrever a documentação na mão. Existem ferramentas excelentes para isso:
Swagger / OpenAPI
swagger.ioO padrão mais usado no mercado. Você descreve sua API em um arquivo YAML ou JSON e a ferramenta gera uma interface visual interativa automaticamente. O desenvolvedor consegue testar os endpoints direto na documentação.
Postman
postman.comAlém de ser a ferramenta mais usada para testar APIs, o Postman permite gerar documentação automaticamente a partir das suas coleções de requisições. É muito usado no dia a dia do desenvolvimento.
Redoc
redocly.comTransforma um arquivo OpenAPI em uma documentação bonita e bem organizada. Fácil de hospedar em qualquer site — sem configuração complexa.
Insomnia
insomnia.restAlternativa ao Postman com interface limpa e suporte a documentação. Muito popular entre desenvolvedores backend pela leveza e simplicidade.
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 /produtosem vez deGET /buscarProdutos -
Use letras minúsculas e hífens Prefira
/pedidos-pendentesem 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.
