O Que É Uma API REST
API REST (Representational State Transfer) é um padrão de arquitetura para comunicação entre sistemas via HTTP. Em termos simples, é a forma como diferentes softwares conversam entre si pela internet.
Quando você usa um app de banco no celular e vê seu saldo, o app está fazendo uma chamada a uma API REST do banco. Quando o Instagram carrega seu feed, está consumindo APIs. Quando uma loja online processa um pagamento, está se comunicando com APIs de gateways como Stripe ou Pagar.me.
APIs REST são a espinha dorsal da internet moderna. Segundo a ProgrammableWeb, existem mais de 24.000 APIs públicas disponíveis, e praticamente toda empresa de tecnologia expõe seus serviços via API.
Para programadores, dominar APIs é uma habilidade essencial que abre portas tanto para emprego quanto para freelancing e criação de produtos próprios.
Conceitos Fundamentais
Recursos e Endpoints
Em uma API REST, tudo é um recurso — um usuário, um produto, um pedido. Cada recurso é acessível através de um endpoint (URL):
```
GET /api/usuarios → Lista todos os usuários
GET /api/usuarios/42 → Retorna o usuário com ID 42
POST /api/usuarios → Cria um novo usuário
PUT /api/usuarios/42 → Atualiza o usuário 42
DELETE /api/usuarios/42 → Remove o usuário 42
```
Métodos HTTP
| Método | Ação | Idempotente | Corpo da Requisição |
|---|---|---|---|
| GET | Ler/buscar dados | Sim | Não |
| POST | Criar recurso | Não | Sim |
| PUT | Atualizar recurso (completo) | Sim | Sim |
| PATCH | Atualizar recurso (parcial) | Sim | Sim |
| DELETE | Remover recurso | Sim | Não |
Status Codes
Os códigos de status HTTP indicam o resultado da operação:
| Código | Significado | Quando Usar |
|---|---|---|
| 200 | OK | Requisição bem-sucedida |
| 201 | Created | Recurso criado com sucesso |
| 204 | No Content | Sucesso sem corpo de resposta |
| 400 | Bad Request | Dados inválidos enviados |
| 401 | Unauthorized | Não autenticado |
| 403 | Forbidden | Sem permissão |
| 404 | Not Found | Recurso não encontrado |
| 422 | Unprocessable Entity | Validação falhou |
| 500 | Internal Server Error | Erro no servidor |
Criando Sua Primeira API com Node.js (Express)
Vamos construir uma API simples para gerenciar tarefas. Primeiro, configure o projeto:
```bash
mkdir minha-api && cd minha-api
npm init -y
npm install express
```
Agora crie o arquivo `server.js`:
```javascript
const express = require('express');
const app = express();
app.use(express.json());
let tarefas = [
{ id: 1, titulo: 'Aprender API REST', concluida: false },
{ id: 2, titulo: 'Criar primeiro projeto', concluida: false }
];
// GET - Listar todas as tarefas
app.get('/api/tarefas', (req, res) => {
res.json(tarefas);
});
// GET - Buscar tarefa por ID
app.get('/api/tarefas/:id', (req, res) => {
const tarefa = tarefas.find(t => t.id === parseInt(req.params.id));
if (!tarefa) return res.status(404).json({ erro: 'Tarefa não encontrada' });
res.json(tarefa);
});
// POST - Criar nova tarefa
app.post('/api/tarefas', (req, res) => {
const { titulo } = req.body;
if (!titulo) return res.status(400).json({ erro: 'Título é obrigatório' });
const novaTarefa = {
id: tarefas.length + 1,
titulo,
concluida: false
};
tarefas.push(novaTarefa);
res.status(201).json(novaTarefa);
});
// PUT - Atualizar tarefa
app.put('/api/tarefas/:id', (req, res) => {
const tarefa = tarefas.find(t => t.id === parseInt(req.params.id));
if (!tarefa) return res.status(404).json({ erro: 'Tarefa não encontrada' });
tarefa.titulo = req.body.titulo || tarefa.titulo;
tarefa.concluida = req.body.concluida ?? tarefa.concluida;
res.json(tarefa);
});
// DELETE - Remover tarefa
app.delete('/api/tarefas/:id', (req, res) => {
const index = tarefas.findIndex(t => t.id === parseInt(req.params.id));
if (index === -1) return res.status(404).json({ erro: 'Tarefa não encontrada' });
tarefas.splice(index, 1);
res.status(204).send();
});
app.listen(3000, () => console.log('API rodando na porta 3000'));
```
Execute com `node server.js` e teste com curl ou Postman.
Criando a Mesma API com Python (FastAPI)
FastAPI é o framework Python mais moderno para construir APIs, com performance próxima a Go e Node.js:
```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
app = FastAPI()
class Tarefa(BaseModel):
titulo: str
concluida: bool = False
tarefas = {}
contador = 0
@app.get("/api/tarefas")
def listar_tarefas():
return list(tarefas.values())
@app.get("/api/tarefas/{tarefa_id}")
def buscar_tarefa(tarefa_id: int):
if tarefa_id not in tarefas:
raise HTTPException(status_code=404, detail="Tarefa não encontrada")
return tarefas[tarefa_id]
@app.post("/api/tarefas", status_code=201)
def criar_tarefa(tarefa: Tarefa):
global contador
contador += 1
nova = {"id": contador, **tarefa.dict()}
tarefas[contador] = nova
return nova
@app.delete("/api/tarefas/{tarefa_id}", status_code=204)
def remover_tarefa(tarefa_id: int):
if tarefa_id not in tarefas:
raise HTTPException(status_code=404, detail="Tarefa não encontrada")
del tarefas[tarefa_id]
```
Para quem está aprendendo Python do zero, FastAPI é uma excelente forma de começar no backend.
Boas Práticas para APIs REST
Naming Conventions
- Use substantivos no plural para recursos: `/usuarios`, `/produtos`
- Use kebab-case para múltiplas palavras: `/categorias-produtos`
- Aninhe recursos relacionados: `/usuarios/42/pedidos`
- Evite verbos na URL — o método HTTP já define a ação
Versionamento
Versione sua API para não quebrar integrações existentes:
```
/api/v1/usuarios → versão 1
/api/v2/usuarios → versão 2
```
Paginação
Para listas grandes, implemente paginação:
```
GET /api/produtos?page=2&limit=20
```
Resposta deve incluir metadados:
```json
{
"data": [...],
"total": 150,
"page": 2,
"limit": 20,
"totalPages": 8
}
```
Autenticação
Use JWT (JSON Web Tokens) ou OAuth 2.0 para proteger endpoints sensíveis. Nunca envie credenciais em query strings.
Rate Limiting
Proteja sua API contra abuso limitando o número de requisições por IP/usuário. Bibliotecas como `express-rate-limit` facilitam a implementação.
Ferramentas Essenciais para Trabalhar com APIs
| Ferramenta | Uso | Preço |
|---|---|---|
| Postman | Testar e documentar APIs | Free/Pago |
| Insomnia | Alternativa leve ao Postman | Free/Pago |
| Swagger/OpenAPI | Documentação automática | Gratuito |
| curl | Testes via terminal | Gratuito |
| Thunder Client | Extensão VS Code para APIs | Gratuito |
Para maximizar sua produtividade, veja nossas recomendações de extensões do VS Code.
Perguntas Frequentes
Qual a diferença entre API REST e API GraphQL?
REST usa endpoints fixos para cada recurso, enquanto GraphQL permite que o cliente especifique exatamente quais dados quer em uma única requisição. REST é mais simples e amplamente adotado; GraphQL é mais flexível e eficiente para aplicações complexas com muitos relacionamentos de dados.
Preciso de banco de dados para criar uma API?
Para aprendizado, não — você pode armazenar dados em memória como nos exemplos acima. Para produção, sim — use PostgreSQL, MongoDB ou outro banco de dados. Serviços como Supabase e PlanetScale facilitam a configuração sem precisar gerenciar infraestrutura.
Quanto ganha um desenvolvedor backend/API?
Desenvolvedores backend que dominam APIs REST, bancos de dados e arquitetura de sistemas ganham em média de R$ 9.000 a R$ 20.000 no Brasil em regime CLT. Especialistas em arquitetura de APIs e microsserviços podem ultrapassar R$ 25.000.
API REST ainda é relevante em 2026?
Absolutamente. Apesar do crescimento de GraphQL e gRPC, REST continua sendo o padrão dominante para a grande maioria das aplicações web e mobile. Sua simplicidade, maturidade e ampla compatibilidade garantem relevância por muitos anos ainda.
