Arquitetura de API REST: Boas Práticas para APIs em Produção

APIs mal projetadas envelhecem mal

Uma API é um contrato. Clientes dependem dela, parceiros integram com ela, times internos a consomem. Uma API mal projetada acumula breaking changes, workarounds e frustração. Uma bem projetada sobrevive anos sem precisar de reescrita.

Design de recursos e endpoints

Substantivos, não verbos

# Errado: verbos na URL
POST /createUser
GET /getUser?id=123
POST /deleteUser

# Certo: substantivos + métodos HTTP
POST /users
GET /users/123
DELETE /users/123

Hierarquia de recursos com moderação

# Razoável
GET /organizations/42/members
POST /organizations/42/members

# Evitar hierarquias profundas
GET /organizations/42/teams/7/projects/3/tasks/99/comments/5
# Melhor:
GET /comments/5  (com filtros de contexto)

Filtros, paginação e ordenação

# Filtros como query params
GET /orders?status=pending&customer_id=42

# Paginação cursor-based (mais eficiente que offset)
GET /orders?cursor=eyJpZCI6MTAwfQ&limit=20

# Ordenação
GET /orders?sort=created_at&order=desc

Respostas consistentes

Defina um envelope de resposta e use-o em toda a API:

// Sucesso
{
  "data": { "id": 1, "name": "Douglas", "email": "..." },
  "meta": { "request_id": "abc-123" }
}

// Lista
{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6MjB9",
    "has_more": true,
    "total": 450
  }
}

// Erro
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dados inválidos",
    "details": [
      { "field": "email", "message": "E-mail inválido" }
    ]
  }
}

Códigos HTTP corretos

| Situação | Código | |----------|--------| | Criou recurso | 201 Created | | Ação assíncrona aceita | 202 Accepted | | Sem conteúdo (DELETE) | 204 No Content | | Recurso não encontrado | 404 Not Found | | Não autorizado (sem auth) | 401 Unauthorized | | Sem permissão (auth ok) | 403 Forbidden | | Validação falhou | 422 Unprocessable Entity | | Rate limit excedido | 429 Too Many Requests |

Versionamento

# URL versioning (mais simples, mais explícito)
/v1/users
/v2/users

# Header versioning (URL mais limpa, menos observável)
Accept: application/vnd.api.v2+json

A regra: versione quando houver breaking change. Mantenha a versão anterior por pelo menos 6 meses após o anúncio de deprecation.

Autenticação e autorização

// Middleware de auth com JWT
export async function authMiddleware(req: Request, res: Response, next: NextFunction) {
  const token = req.headers.authorization?.replace('Bearer ', '')
  
  if (!token) {
    return res.status(401).json({ error: { code: 'UNAUTHORIZED' } })
  }
  
  try {
    const payload = jwt.verify(token, process.env.JWT_SECRET!) as JwtPayload
    req.user = payload
    next()
  } catch {
    return res.status(401).json({ error: { code: 'TOKEN_INVALID' } })
  }
}

// Verificação de permissão por recurso
export function requirePermission(permission: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!req.user.permissions.includes(permission)) {
      return res.status(403).json({ error: { code: 'FORBIDDEN' } })
    }
    next()
  }
}

Rate Limiting

Proteger a API de abuso e DDoS:

import rateLimit from 'express-rate-limit'

// Limite geral
app.use(rateLimit({
  windowMs: 15 * 60 * 1000,  // 15 minutos
  max: 100,
  standardHeaders: true,
  legacyHeaders: false,
  message: { error: { code: 'RATE_LIMIT_EXCEEDED' } }
}))

// Limite mais restrito para autenticação
app.use('/auth', rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 10,
  skipSuccessfulRequests: true  // não conta tentativas bem-sucedidas
}))

Documentação com OpenAPI

openapi: 3.1.0
info:
  title: API de Pedidos
  version: 2.0.0
paths:
  /orders:
    get:
      summary: Listar pedidos
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, processing, completed, cancelled]
      responses:
        '200':
          description: Lista de pedidos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'

Use swagger-jsdoc e swagger-ui-express para gerar a documentação automaticamente a partir dos comentários no código.

Idempotência para operações críticas

Pagamentos, envios de e-mail, criação de recursos — operações que não devem ser executadas duas vezes:

// Cliente envia Idempotency-Key: uuid-unico
// Servidor armazena resultado por 24h associado à chave

async function handlePayment(req: Request) {
  const idempotencyKey = req.headers['idempotency-key']
  
  if (idempotencyKey) {
    const cached = await cache.get(`idempotency:${idempotencyKey}`)
    if (cached) return JSON.parse(cached)  // retorna resultado anterior
  }
  
  const result = await processPayment(req.body)
  
  if (idempotencyKey) {
    await cache.set(`idempotency:${idempotencyKey}`, JSON.stringify(result), 'EX', 86400)
  }
  
  return result
}

Conclusão

APIs bem projetadas são um investimento. O tempo gasto em consistência de resposta, versionamento cuidadoso, autenticação robusta e documentação atualizada retorna em velocidade de integração, menos suporte e longevidade do contrato. Projeta-se uma API esperando que ela dure anos.