Laravel API Boas Práticas: Como Criar APIs Seguras e Performáticas?

1. Segurança: configuração, headers e limites

1.1 Variáveis de ambiente

Configure corretamente seu arquivo .env em produção:

APP_ENV=production
APP_DEBUG=false
LOG_LEVEL=error

Motivo: Evita vazamento de informações sensíveis e garante que erros não sejam exibidos em tela.

1.2 SecurityHeadersMiddleware

Crie um middleware para adicionar headers de segurança a todas as respostas HTTP:

$response->headers->set('Content-Security-Policy', $csp);
$response->headers->set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');
$response->headers->set('X-Frame-Options', 'DENY');
$response->headers->set('X-Content-Type-Options', 'nosniff');
$response->headers->set('Referrer-Policy', 'no-referrer');
$response->headers->set('X-Powered-By', '');
$response->headers->set('X-XSS-Protection', '1; mode=block');

1.3 Cookies e Same Site

Ao lidar com cookies, defina configurações seguras:

'secure' => true,
'http_only' => true,
'same_site' => 'strict',

Secure: True

• Diz ao navegador que o cookie só pode ser transmitido por conexões HTTPS
• Isso impede que o cookie (por exemplo, de sessão ou autenticação) seja interceptado em uma conexão HTTP comum

HTTP Only: True

• Impede que o cookie seja acessado por JavaScript (via document.cookie)
• Ele só pode ser enviado automaticamente pelo navegador em requisições HTTP

Same Site: Strict

• Controla quando o cookie é enviado em requisições de outros sites (cross-site)
• 'strict' é o modo mais seguro: o cookie só é enviado se o usuário estiver navegando diretamente no mesmo domínio.

1.4 Rate Limit e limite de Payload

• Rate limit: limite de 30 requisições por minuto por API — se ultrapassado, retorne 429 Too Many Requests.
• Payload máximo: 1KB (+/-1000 linhas de JSON). Ultrapassou? Retorne 413 Content Too Large.

Essas medidas reduzem abusos e mantêm o servidor saudável.

2. Autenticação, validação e sanitização

2.1 Autenticação com Bearer Token

Use tokens do tipo Bearer em cabeçalhos HTTP:

Authorization: Bearer token eyJhbGciOi...

Valide o token via middleware e retorne 401 Unauthorized se for inválido, ou 403 Forbidden se o usuário não tiver permissão.

2.2 Middleware de Sanitização de Payload

Evite injeções e ataques XSS limpando a entrada de dados:

public function handle($request, Closure $next) {
  $input = $request->all();
  array_walk_recursive($input, function (&$v) {
    $v = strip_tags($v);
    $v = preg_replace('/javascript:\s*/i', '', $v);
  });
  $request->merge($input);
  return $next($request);
}

2.3 Requests Validados

Use FormRequest para validar e remover campos não permitidos:

• Valide tipos, tamanhos de string e formatos recebidos
• Converta dados (ex: datas para timestamps).
• Retorne 422 Unprocessable Entity com erros em JSON.

3. Performance: filas, consultas e paginação

3.1 Use filas para operações pesadas

Evite processar cadastros e updates em tempo real. Em vez disso:

1. Receba o payload.
2. Valide e retorne 202 Accepted.
3. Envie a tarefa para uma fila (Redis, SQS, Beanstalkd) e mande um JOB ou uma CRON processar depois.

Isso melhora o tempo de resposta e evita bloqueios em endpoints críticos.

Eu defendo que são poucas as situações que um cadastro tem que ser feito em tempo real, então TUDO que você pude jogar em fila para sempre processa daqui 1 minuto que seja, faça.

3.2 Paginação em Consultas

Nunca retorne grandes coleções sem paginação:

{
  "data": [...],
  "pagination": { "page": 1, "per_page": 20, "total": 50 }
}

3.3 Prefira DB Query Builder

Para endpoints com alta carga, use DB::table ao invés do Eloquent:

$rows = DB::table('users')
  ->select('id','name','email','deleted_at')
  ->where('active', 1)
  ->paginate(20);

Se você usa SoftDeleles, não esqueça adicionar ->whereNull(‘deleted_at’)

Isso reduz overhead e garante performance em escala.

4. Design de API e boas práticas de resposta

4.1 Sempre retornar JSON com status correto

// Sucesso
HTTP/1.1 200 OK
{ "success": true, "data": {...} }

// Processamento assíncrono
HTTP/1.1 202 Accepted
{ "success": true, "message": "Registro será processado em breve." }

// Erros de validação
HTTP/1.1 422 Unprocessable Entity
{ "success": false, "errors": { "email": ["Formato inválido"] } }

4.2 Logs e monitoramento

Use ferramentas como Sentry, Datadog ou Laravel Telescope para:

• Monitorar erros 4xx e 5xx;
• Acompanhar tempo médio de resposta;
• Auditar filas e jobs pendentes.

4.3 Documentação e versionamento

Use OpenAPI/Swagger para documentar endpoints e mantenha versionamento (/v1/, /v2/) para evitar quebra de contratos entre clientes e servidores.

Para saber mais sobre: Swagger