O que é RESTful?

RESTful é um estilo arquitetural para desenvolvimento de APIs baseado no REST (Representational State Transfer), proposto por Roy Fielding em sua tese de doutorado em 2000. APIs RESTful utilizam os protocolos HTTP e seus métodos para manipulação de recursos, promovendo sistemas escaláveis, flexíveis e de fácil integração.

É amplamente utilizado para criar serviços web modernos, conectando aplicações móveis, web e IoT.

Princípios Fundamentais do REST

• Cliente-Servidor: Separação clara entre cliente e servidor, facilitando a evolução independente.
• Sem Estado (Stateless): Cada requisição HTTP contém todas as informações necessárias para o servidor processar, sem manter estado entre chamadas.
• Cacheável: Respostas devem definir se podem ser armazenadas para melhorar desempenho.
• Interface Uniforme: Simplifica e desacopla a arquitetura. Isso inclui identificação de recursos via URIs, manipulação de recursos via representações e auto-descrição das mensagens.
• Sistema em Camadas: Cliente não deve saber se está comunicando diretamente com servidor final ou intermediário (ex: proxy, gateway).
• Code on Demand (opcional): Servidor pode enviar código executável ao cliente para extensões temporárias.

Recursos e Endpoints

REST organiza dados em recursos, que são representações de entidades (ex: usuários, produtos, pedidos). Cada recurso é identificado por uma URI única.

Exemplo:

• GET /usuarios — lista todos os usuários
• GET /usuarios/123 — obtém detalhes do usuário com ID 123
• POST /usuarios — cria um novo usuário
• PUT /usuarios/123 — atualiza o usuário 123
• DELETE /usuarios/123 — remove o usuário 123

Métodos HTTP Usados em APIs RESTful

• GET: Recupera recurso(s). Deve ser idempotente e sem efeitos colaterais.
• POST: Cria um novo recurso ou executa operações que modificam o estado.
• PUT: Atualiza um recurso completo. Também idempotente.
• PATCH: Atualiza parcialmente um recurso.
• DELETE: Remove um recurso.
• OPTIONS: Consulta quais métodos são suportados por um endpoint.

Status HTTP Comuns

APIs RESTful usam códigos HTTP para indicar o resultado da requisição:

• 200 OK — Sucesso na requisição.
• 201 Created — Recurso criado com sucesso (resposta a POST).
• 204 No Content — Requisição bem sucedida, sem corpo na resposta.
• 400 Bad Request — Requisição inválida ou malformada.
• 401 Unauthorized — Falha na autenticação.
• 403 Forbidden — Cliente não tem permissão.
• 404 Not Found — Recurso não encontrado.
• 409 Conflict — Conflito, como tentativa de criar recurso duplicado.
• 500 Internal Server Error — Erro do servidor.

Exemplo Prático: API RESTful em Node.js com Express

Um endpoint simples para manipular usuários:

const express = require('express');
const app = express();
app.use(express.json());

let usuarios = [
  { id: 1, nome: 'Alice', email: 'alice@exemplo.com' },
  { id: 2, nome: 'Bob', email: 'bob@exemplo.com' }
];

// Listar todos os usuários
app.get('/usuarios', (req, res) => {
  res.json(usuarios);
});

// Obter usuário por id
app.get('/usuarios/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const usuario = usuarios.find(u => u.id === id);
  if (!usuario) return res.status(404).json({ erro: 'Usuário não encontrado' });
  res.json(usuario);
});

// Criar usuário
app.post('/usuarios', (req, res) => {
  const { nome, email } = req.body;
  const id = usuarios.length ? usuarios[usuarios.length - 1].id + 1 : 1;
  const novoUsuario = { id, nome, email };
  usuarios.push(novoUsuario);
  res.status(201).json(novoUsuario);
});

// Atualizar usuário
app.put('/usuarios/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const index = usuarios.findIndex(u => u.id === id);
  if (index === -1) return res.status(404).json({ erro: 'Usuário não encontrado' });
  const { nome, email } = req.body;
  usuarios[index] = { id, nome, email };
  res.json(usuarios[index]);
});

// Deletar usuário
app.delete('/usuarios/:id', (req, res) => {
  const id = parseInt(req.params.id);
  usuarios = usuarios.filter(u => u.id !== id);
  res.status(204).send();
});

app.listen(3000, () => console.log('API rodando na porta 3000'));

Boas Práticas para APIs RESTful

• Design de URIs: Use nomes no plural para recursos, evite verbos.
• Versionamento: Inclua versão na URI, ex: /v1/usuarios, para facilitar atualizações.
• Documentação clara: Use ferramentas como Swagger/OpenAPI para descrever sua API.
• Paginação: Para coleções grandes, implemente paginação via query params (ex: ?page=2&limit=20).
• Filtragem e ordenação: Permita filtrar e ordenar resultados para melhorar a experiência do cliente.
• Erros estruturados: Padronize o formato das mensagens de erro para facilitar debugging.
• Segurança: Sempre use HTTPS, implemente autenticação e controle de acesso.

RESTful vs Outros Estilos de API

Comparado a outras arquiteturas, REST tem:

• SOAP: Mais simples, leve e baseado em HTTP padrão.
• GraphQL: Permite consultas flexíveis, mas é mais complexo e não usa HTTP diretamente para cada operação.
• gRPC: Baseado em RPC, eficiente para comunicação entre serviços internos.