Nossa API é construída com Hono no Cloudflare Workers, otimizando para baixa latência e distribuição global. Aqui está como a construímos e mantemos.
Framework Hono
Escolhemos o Hono por seu tamanho leve e design edge-first:
- Bundle minúsculo: O Hono adiciona overhead mínimo ao tamanho do Worker, mantendo os cold starts rápidos.
- Padrões familiares: O roteamento semelhante ao Express facilita o onboarding dos desenvolvedores.
- Middleware integrado: CORS, compressão e logging funcionam out-of-the-box.
- Segurança de tipos: Suporte completo a TypeScript com tipagem de requisição/resposta.
Design Edge-First
Cada decisão de API considera restrições de implantação na borda:
- Handlers sem estado: Sem sessões no lado do servidor ou armazenamento local entre requisições.
- Estado externo: Todo o estado vive no Supabase (SQL), Cloudflare KV (chave-valor) ou R2 (blobs).
- Otimização de cold start: Inicialização lazy de clientes pesados (Stripe, Supabase) apenas quando necessário.
- Roteamento regional: A Cloudflare roteia automaticamente as requisições para o local de borda mais próximo.
Validação de Requisições
O Zod fornece segurança de tipos em tempo de execução para todos os dados de entrada:
- Definições de esquema: Cada endpoint define sua forma de entrada esperada com esquemas Zod.
- Análise automática: Requisições inválidas falham rapidamente com mensagens de erro claras.
- Inferência de tipos: Os tipos TypeScript são derivados dos esquemas, garantindo consistência.
- Transformações: O Zod lida com coerção (string para número) e padrões de forma limpa.
Tratamento de Erros
Respostas de erro consistentes facilitam a depuração:
- Formato estruturado: Todos os erros retornam JSON com erro, mensagem e detalhes opcionais.
- Códigos de status HTTP: Usamos códigos apropriados (400 para validação, 401 para auth, 403 para permissões, 429 para limites de taxa).
- Rastreamento de erros: As exceções são registradas com contexto da requisição para depuração.
- Mensagens amigáveis ao usuário: Os detalhes técnicos são registrados, mas não expostos aos clientes.
Limitação de Taxa
Nossa estratégia de limitação de taxa protege o sistema enquanto é justa:
- Limites em camadas: Limites diferentes para endpoints de rastreamento (alto), endpoints de API (médio) e endpoints de auth (baixo).
- Rastreamento por chave: As chaves de API têm cotas individuais baseadas no tier de assinatura.
- Janela deslizante: Os limites são calculados em janelas de tempo contínuas, não períodos fixos.
- Degradação graciosa: As requisições com limite de taxa recebem headers Retry-After.
Organização de Endpoints
As rotas são organizadas por domínio para manutenibilidade:
- /e/:trackingCode — Rastreamento público (amigável a bloqueadores de anúncios)
- /api/analytics/* — Consultas de dados do dashboard
- /api/replay/* — Gerenciamento de replay de sessão
- /api/billing/* — Integração com Stripe
- /api/team/:teamId/* — Operações com escopo de equipe
- /api/external/v1/* — Acesso à API de terceiros
- /api/cron/* — Gatilhos de tarefas agendadas (autenticação via webhook)