Integração e API

API Gateway

Diferente de um reverse proxy genérico, um API Gateway adiciona gestão orientada a APIs: autenticação, quotas, rate limiting, versionamento, transformação e telemetria. Produtos como Azure API Management, Amazon API Gateway e Kong operam sobre HTTP, REST, WebSocket ou gRPC. O gateway cria um endpoint único para serviços internos. A implantação precisa preservar cabeçalhos, identidade e TLS; mal dimensionado, torna-se gargalo, ponto único de falha e camada de acoplamento.

🔀 Tipos de Comunicação

HTTP

Proxy de requisições HTTP e REST

O gateway recebe uma requisição em um endpoint público, valida a política e encaminha para um serviço interno. Pode reescrever caminho, host, cabeçalho e método; encerrar TLS; selecionar upstream; aplicar timeout e normalizar resposta. Em uma plataforma de casa inteligente, `/v1/casas/{id}/dispositivos` pode ser exposto externamente enquanto serviços internos usam nomes e portas privados. O gateway não deve esconder contratos mal definidos. Reescritas excessivas dificultam rastreio. Cabeçalhos como `Authorization`, `Host`, `X-Forwarded-For`, `Forwarded` e IDs de correlação precisam de política explícita. Dados do cliente não devem ser aceitos de cabeçalhos forjados sem uma borda confiável. O serviço interno precisa saber qual identidade foi autenticada e qual contexto foi validado.

MULTI-API

Gerenciamento de APIs REST, GraphQL e gRPC

Plataformas modernas gerenciam REST, GraphQL, gRPC e, em alguns produtos, WebSocket. Cada estilo exige tratamento diferente. REST usa recursos, métodos e códigos HTTP. GraphQL concentra consultas num endpoint e precisa de limites de profundidade e custo. gRPC usa HTTP/2 e Protocol Buffers, exigindo suporte a streaming, trailers e content type. Um gateway que converte gRPC para JSON pode ampliar clientes, mas introduz transformação e perda potencial de recursos. A decisão deve considerar compatibilidade ponta a ponta. Não basta o produto listar “gRPC”; health checks, observabilidade, mTLS e tamanho de mensagem precisam ser validados.

POLICY

Políticas de segurança e controle de consumo

Autenticação JWT, OAuth 2.0, OpenID Connect, mTLS, API keys, quotas e rate limiting são funções comuns. A política pode exigir escopo `devices:write`, validar `iss`, `aud`, expiração e assinatura, e limitar um cliente a 100 requisições por minuto. O gateway deve usar relógio correto e cache de chaves com atualização segura. Uma API key identifica aplicação, mas não necessariamente usuário. Rate limiting local por instância pode permitir excesso num cluster; um backend distribuído ou algoritmo coordenado pode ser necessário. Limites precisam diferenciar leitura de telemetria e comando de fechadura. Respostas `429 Too Many Requests` devem incluir informação de retry quando aplicável. O gateway não substitui autorização no serviço quando o contexto de negócio é interno.

BFF

Agregação e Backend for Frontend

Um gateway pode chamar vários serviços e compor uma resposta adaptada ao aplicativo móvel, painel ou assistente de voz. O padrão Backend for Frontend reduz round trips e dados desnecessários. Um painel de residência pode receber numa única chamada clima, energia e alertas. A agregação aumenta acoplamento e latência de cauda. Se um serviço demora, toda a resposta pode esperar. Timeouts, fallback e respostas parciais precisam ser projetados. Lógica de negócio extensa no gateway cria um monólito de borda. A recomendação é manter políticas transversais e composição limitada, deixando regras de domínio nos serviços. Gateways separados por cliente ou domínio podem reduzir congestionamento organizacional.

✅ Vantagens Arquiteturais

⚡

Centraliza políticas sem replicar código em cada serviço

Autenticação, logging, limitação, CORS, cabeçalhos de segurança e transformação podem ser aplicados num ponto administrado. Isso reduz implementações divergentes. Azure API Management, Kong, Apigee e Amazon API Gateway oferecem políticas e plugins. A centralização também concentra risco: uma regra errada pode bloquear todas as integrações ou expor dados. Configuração precisa ser versionada como código, revisada e promovida por ambientes. Mudanças devem ter testes de contrato e canary. Não editar políticas críticas manualmente em produção sem rastreio. O gateway é infraestrutura de segurança e precisa do mesmo rigor que código.

⚡

Oculta a topologia interna e estabiliza o endpoint do cliente

Clientes não precisam conhecer cada microserviço. Serviços podem mudar de endereço, ser divididos ou escalados, mantendo o contrato externo. Isso facilita evolução. O gateway não elimina versionamento: mudanças incompatíveis no payload continuam exigindo nova versão, compatibilidade ou negociação. Um endpoint estável deve ter SLO, documentação e política de depreciação. Em automação, aplicativos instalados por anos podem permanecer desatualizados. A API precisa suportar janelas longas. O gateway pode rotear `/v1` e `/v2`, mas a equipe ainda mantém ambas. A ocultação técnica não deve esconder dependências operacionais.

⚡

Melhora observabilidade na fronteira do sistema

Como todas as chamadas passam pela borda, o gateway mede volume, latência, status, cliente, rota e tamanho. Tracing distribui `traceparent` segundo W3C Trace Context. Dashboards mostram p50, p95 e p99. Logs precisam mascarar tokens, senhas, códigos de fechadura e conteúdo pessoal. Métricas agregadas são preferíveis a payload. O gateway deve distinguir latência própria e do upstream. Um aumento de p99 pode vir de serviço, DNS, TLS ou política pesada. IDs de correlação precisam atravessar. A observabilidade central ajuda, mas não substitui métricas internas dos serviços.

⚡

Permite controle de custos e capacidade por consumidor

Quotas e planos limitam uso de APIs de nuvem. Uma integração doméstica defeituosa pode entrar em loop e gerar milhares de chamadas. O gateway pode limitar por chave, usuário, residência ou IP. A política precisa considerar NAT: várias casas podem compartilhar um endereço. Rate limiting por IP isolado pode bloquear usuários legítimos. Tokens e client IDs oferecem granularidade. Cotas diárias ajudam a controlar custo. Para comandos de segurança, o limite também protege contra abuso. O sistema deve permitir rajadas normais, como sincronização após reconexão, sem negar tudo. Token bucket e sliding window são escolhas com efeitos diferentes.

⚡

Suporta implantação híbrida e integração local-cloud

Gateways self-hosted, como opções do Azure API Management, Kong ou Tyk, podem executar próximos aos serviços locais, enquanto a gestão fica central. Em automação predial, uma instância local mantém acesso a APIs do edifício e aplica políticas mesmo com conectividade limitada, conforme o produto. O desenho precisa definir cache de configuração, modo desconectado e sincronização. Um gateway cloud não alcança automaticamente uma VLAN residencial. VPN, túnel ou agente é necessário. A interoperabilidade entre local e nuvem aumenta a superfície de ataque. mTLS, rotação de certificados e segmentação são fundamentais.

Exemplo de Código

# Exemplo de rota em Kong declarativo
services:
- name: automacao-api
  url: http://automacao-interna:8080
  routes:
  - name: dispositivos-v1
    paths: ['/v1/dispositivos']
plugins:
- name: rate-limiting
  config: { minute: 100, policy: redis }
# JWT/OIDC e mTLS devem ser configurados conforme o modelo de identidade.

Azure API ManagementHTTP/HTTPS, REST, SOAP, GraphQL, WebSocket e suporte a APIs gRPC conforme recursos atuais. O gateway de runtime recebe requisições, aplica políticas, faz proxy e coleta telemetria. Instâncias gerenciadas e gateways self-hosted atendem topologias cloud e híbridas. Políticas podem validar JWT, transformar, limitar e cachear. A implantação precisa considerar tiers, capacidade, regiões, rede privada e dependências. Configuração deve ser automatizada por ARM, Bicep, Terraform ou pipeline.

Amazon API GatewayREST APIs, HTTP APIs e WebSocket APIs integradas a AWS Lambda, serviços AWS e endpoints HTTP. Oferece autorização IAM, JWT/Lambda authorizers, throttling, quotas, stages e observabilidade. REST API e HTTP API têm conjuntos de recursos e custos diferentes. Integrações síncronas possuem limites de timeout e payload definidos pelo serviço. A escolha precisa considerar latência, recursos e preço. Para dispositivos IoT, Amazon IoT Core pode ser mais apropriado que usar API Gateway como broker MQTT.

Kong GatewayProxy baseado em NGINX/OpenResty para HTTP, HTTPS, gRPC e outros recursos conforme edição. Plugins adicionam autenticação, OIDC, rate limiting, transformação, logging e observabilidade. Pode operar declarativamente, com banco ou em modo híbrido. É comum em Kubernetes e ambientes locais. O administrador precisa gerir banco, control plane, data planes, certificados e upgrades. Plugins customizados ampliam capacidade e risco. O gateway não substitui um service mesh para todo tráfego leste-oeste.

Google ApigeePlataforma de gerenciamento para APIs REST, SOAP e integrações empresariais, com proxies, policies, analytics, monetização e developer portals. Adequada a programas de API com governança, não apenas a encaminhamento simples. A complexidade operacional e comercial é maior que a de um reverse proxy NGINX. Em ecossistemas de casa inteligente de grande escala, pode gerenciar APIs de parceiros e aplicativos. Para uma instalação residencial local, seria desproporcional.