Padrões de gateway de API e práticas recomendadas para aplicativos modernos

Os gateways de API lidam com uma média de 83% de todo o tráfego corporativo, servindo como ponto de entrada único para aplicativos clientes. Um gateway de API bem projetado simplifica a comunicação cliente-servidor, aplica políticas de segurança e fornece observabilidade em todos os serviços. Um projeto mal projetado torna-se um gargalo e um ponto único de falha.

Este guia aborda padrões de arquitetura de gateway de API, seleção de tecnologia e práticas recomendadas de implementação para aplicativos da web, sistemas ERP e plataformas de comércio eletrônico.

Principais conclusões

• Os gateways de API centralizam questões transversais (autenticação, limitação de taxa, registro) para eliminar a duplicação entre serviços
• A limitação de taxa no nível do gateway protege os serviços de back-end contra picos de tráfego e abusos
• Padrões de disjuntores evitam falhas em cascata quando os serviços downstream não são íntegros
• O versionamento de API por meio do gateway permite uma evolução compatível com versões anteriores de sua superfície de API

---

Padrões de gateway principais

Padrão 1: Roteamento de solicitação

O gateway roteia solicitações para o serviço de back-end apropriado com base no caminho da URL, nos cabeçalhos ou em outros atributos da solicitação.

# Nginx as API gateway
upstream api_service {
    server api-1:3001;
    server api-2:3001;
}

upstream auth_service {
    server auth:9000;
}

upstream web_service {
    server web:3000;
}

server {
    listen 443 ssl;
    server_name api.example.com;

    location /api/v1/ {
        proxy_pass http://api_service;
    }

    location /auth/ {
        proxy_pass http://auth_service;
    }

    location / {
        proxy_pass http://web_service;
    }
}

Padrão 2: Autenticação e Autorização

Centralize a autenticação no gateway para evitar implementá-la em todos os serviços.

// NestJS middleware for JWT validation at the gateway level
@Injectable()
export class GatewayAuthMiddleware implements NestMiddleware {
  constructor(private readonly jwtService: JwtService) {}

  async use(req: Request, res: Response, next: NextFunction) {
    // Skip public endpoints
    if (this.isPublicEndpoint(req.path)) {
      return next();
    }

    const token = this.extractToken(req);
    if (!token) {
      throw new UnauthorizedException('Missing authentication token');
    }

    try {
      const payload = await this.jwtService.verifyAsync(token);
      req['user'] = payload;
      next();
    } catch {
      throw new UnauthorizedException('Invalid token');
    }
  }

  private extractToken(req: Request): string | undefined {
    // Check cookie first, then Authorization header
    return req.cookies?.ecosire_auth
      || req.headers.authorization?.replace('Bearer ', '');
  }

  private isPublicEndpoint(path: string): boolean {
    const publicPaths = ['/health', '/api/v1/products', '/api/v1/blog'];
    return publicPaths.some(p => path.startsWith(p));
  }
}

Padrão 3: Limitação de taxa

// Rate limiting configuration per endpoint type
const rateLimits = {
  public: { windowMs: 60000, max: 100 },     // 100 req/min for public APIs
  authenticated: { windowMs: 60000, max: 500 }, // 500 req/min for authenticated users
  admin: { windowMs: 60000, max: 1000 },       // 1000 req/min for admin
  webhooks: { windowMs: 60000, max: 50 },       // 50 req/min for webhooks
};

Padrão 4: Disjuntor

Quando um serviço downstream falha, o disjuntor evita falhas em cascata:

[Closed] --> (failures exceed threshold) --> [Open] --> (timeout expires) --> [Half-Open]
    ^                                                                            |
    |                                        (success)                           |
    +--------------------------------------------------------------------<-------+
    |                                        (failure)                           |
    |                                           +-------->  [Open]

Estados:

• Fechado: As solicitações passam normalmente. Rastreie a contagem de falhas.
• Aberto: todas as solicitações falham imediatamente sem chamar o serviço. Retornar resposta em cache/fallback.
• Semi-aberto: permite a passagem de uma solicitação. Se tiver sucesso, feche o circuito. Se falhar, reabra.

Padrão 5: Cache de Resposta

# Cache GET responses for public endpoints
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:10m max_size=1g inactive=60m;

location /api/v1/products {
    proxy_pass http://api_service;
    proxy_cache api_cache;
    proxy_cache_valid 200 5m;
    proxy_cache_valid 404 1m;
    proxy_cache_key "$scheme$request_method$host$request_uri";
    add_header X-Cache-Status $upstream_cache_status;
}

---

Estratégias de versionamento de API

Recomendação: controle de versão do caminho de URL. É o mais explícito, mais depurável e mais fácil de rotear no nível do gateway.

Mudanças significativas versus alterações não significativas

---

Comparação de tecnologia de gateway

Para a maioria das pequenas e médias empresas: o Nginx é suficiente. Ele lida com roteamento, terminação SSL, limitação de taxa e armazenamento em cache com sobrecarga de menos de um milissegundo. Atualize para Kong quando precisar de recursos avançados de plug-in (OAuth2, transformação de solicitação, análise).

---

Observabilidade no Gateway

Registro de solicitação

log_format gateway '$remote_addr - $remote_user [$time_local] '
                   '"$request" $status $body_bytes_sent '
                   '"$http_referer" "$http_user_agent" '
                   '$request_time $upstream_response_time '
                   '$http_x_request_id';

access_log /var/log/nginx/gateway.log gateway;

Coleção de métricas

Acompanhe essas métricas no nível do gateway:

• Taxa de solicitação por endpoint, método e código de status
• Distribuição de latência (P50, P95, P99) por endpoint
• Taxa de erros por endpoint e tipo de erro
• Limite de taxas atingidas por cliente
• Proporção de acertos de cache por endpoint
• Tempo de resposta upstream versus tempo de resposta total

---

Tratamento de erros no gateway

Respostas de erro consistentes

O gateway deve normalizar as respostas de erro de diferentes serviços de back-end:

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The requested service is temporarily unavailable",
    "requestId": "req_abc123",
    "timestamp": "2026-03-16T14:32:01Z"
  }
}

Configuração de novas tentativas e tempo limite

location /api/ {
    proxy_pass http://api_service;

    # Timeout configuration
    proxy_connect_timeout 5s;
    proxy_send_timeout 30s;
    proxy_read_timeout 30s;

    # Retry on connection errors only (not on 5xx)
    proxy_next_upstream error timeout;
    proxy_next_upstream_tries 2;

    # Custom error pages
    error_page 502 503 504 /api-error.json;
}

Degradação Graciosa

Quando um serviço de back-end não crítico fica inativo, o gateway pode servir respostas armazenadas em cache ou dados substitutos em vez de retornar erros:

---

Padrões de segurança de gateway

Solicitar Validação

Valide a estrutura da solicitação antes de encaminhar para serviços de back-end:

• Rejeitar solicitações com tipos de conteúdo desconhecidos
• Aplicar tamanho máximo do corpo da solicitação por endpoint
• Validar cabeçalhos necessários (versão da API, tipo de conteúdo)
• Remova cabeçalhos suspeitos (cabeçalhos salto a salto, cabeçalhos internos do servidor)

Lista de permissões de IP para endpoints de administrador

location /api/admin/ {
    allow 203.0.113.0/24;  # Office IP range
    allow 10.0.0.0/8;      # Internal network
    deny all;

    proxy_pass http://api_service;
}

Solicitar transformação

O gateway pode adicionar, modificar ou remover cabeçalhos antes de encaminhar:

location /api/ {
    proxy_pass http://api_service;

    # Add security headers
    proxy_set_header X-Request-ID $request_id;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;

    # Remove internal headers from responses
    proxy_hide_header X-Powered-By;
    proxy_hide_header Server;
}

---

Perguntas frequentes

Precisamos de um gateway de API para um aplicativo monolítico?

Sim, mas mais simples. Mesmo para um monólito, o Nginx como proxy reverso fornece terminação SSL, limitação de taxa, serviço de arquivo estático e cabeçalhos de segurança. Você não precisa do Kong ou do AWS API Gateway para um monólito, mas precisa de algo entre a Internet e o servidor de aplicativos.

Como lidamos com o failover do gateway de API?

Execute várias instâncias de gateway por trás de um balanceador de carga em nuvem (AWS ALB, Cloudflare). Se uma instância de gateway falhar, o balanceador de carga roteará o tráfego para instâncias íntegras. Para Nginx, use verificações de integridade ativas e remoção automática de upstreams não saudáveis.

O gateway da API deve lidar com a autenticação ou cada serviço deve?

O gateway deve lidar com a autenticação (verificando se o token é válido). Os serviços individuais devem tratar da autorização (verificando se o usuário autenticado tem permissão para a ação específica). Essa separação mantém o gateway leve e permite que os serviços tomem decisões de controle de acesso refinadas.

Como lidamos com o CORS no gateway da API?

Configure o CORS no nível do gateway para evitar a duplicação de cabeçalhos CORS entre serviços. Defina Access-Control-Allow-Origin para seus domínios frontend específicos (nunca use * em produção com credenciais). Lide com solicitações OPTIONS de simulação no gateway para reduzir a carga nos serviços de back-end.

---

O que vem a seguir

Um gateway de API é a porta de entrada para sua infraestrutura. Combine-o com monitoramento para visibilidade, fortalecimento de segurança para proteção e teste de carga para planejamento de capacidade.

Entre em contato com a ECOSIRE para obter consultoria de arquitetura de API ou explore nosso guia DevOps para obter o roteiro completo de infraestrutura.

---

Publicado pela ECOSIRE – ajudando empresas a construir infraestrutura de API escalonável.