APIs que ninguém precisa quebrar pra usar
Design e build de APIs públicas e internas com contratos versionados, OpenAPI gerado a partir do código, observability ponta a ponta e idempotência onde precisa — pra integrar parceiros sem virar passivo técnico.
O problema que vemos no mercado
API mal desenhada é dívida que cobra juros compostos. Vimos times pagando por isso de quatro formas. Primeira: documentação que diverge do código — o time externo testa o endpoint que está no Swagger, o servidor responde diferente, o suporte trabalha 4 horas pra explicar que "a doc está desatualizada". Segunda: contratos sem versionamento — qualquer mudança quebra cliente em produção, time de integração vive com medo de mexer. Terceira: auth ad-hoc — token sem rotação, escopos sem granularidade, secret no Slack interno, sem auditoria de quem chamou o que.
Quarta e mais comum: webhooks sem idempotência. O parceiro envia o webhook duas vezes (porque sempre envia — retry é parte do protocolo), o sistema cria dois pedidos, e a operação descobre na conciliação financeira do mês seguinte. Pra cada hora de build economizada por pular essa parte, gastam-se dez horas de suporte arrumando estado divergente em produção.
O resultado típico desses quatro problemas: a API funciona, mas ninguém quer mexer nela. Quando o produto precisa evoluir, o time prefere construir uma API paralela em vez de quebrar a que existe. Em 3-4 anos, o cliente tem três APIs fazendo coisas parecidas e nenhuma documentada direito. Cada parceiro novo integra escolhendo qual versão usar e ninguém sabe responder.
Como entregamos
O contrato vem antes do código. Desenhamos OpenAPI 3.1 (ou GraphQL schema) primeiro, revisamos com quem vai consumir, e só depois implementamos. Esquemas de request/response definidos em Zod no servidor — o mesmo schema gera OpenAPI automaticamente e valida payload em runtime, eliminando o drift entre doc e código que mata times de integração. Quando o cliente quer SDK em TypeScript pra os consumidores, geramos a partir do OpenAPI; quando precisa de Python ou Go, geramos pelas ferramentas oficiais.
Versionamento é decisão de produto, não de URL. Versão major na URL (`/v1`, `/v2`) só quando há quebra real; versionamento minor via header `Api-Version` ou negociação de content-type pra mudanças aditivas. Endpoint deprecated ganha header `Sunset` com data, comunicado por email aos consumidores ativos (rastreáveis pelos logs), e período de coexistência mínimo de 6 meses. Quem consome a API sabe quando algo vai mudar antes de mudar.
Idempotência é requisito não-negociável em qualquer endpoint que muda estado. Toda mutação aceita header `Idempotency-Key`; chave + payload + endpoint ficam em Postgres com janela de retenção de 24h-7d (depende do caso). Retry no cliente é seguro. Webhooks que recebemos passam pela mesma lógica — chave de idempotência derivada do payload da contraparte, retentativa silenciosa não duplica efeito.
Auth é OAuth 2.0 com client credentials pra m2m ou Authorization Code + PKCE pra integrações com usuário humano. JWT assinado por chave do servidor, rotacionável; escopos granulares (`pedido:read`, `pedido:write`, `cliente:read` em vez de "tudo"). Secret nunca em código — sempre em vault (HashiCorp Vault quando o cliente já tem, AWS Secrets Manager ou Doppler em casos menores). Audit log de cada chamada bem-sucedida e cada negação.
Observability é tracing distribuído. OpenTelemetry instrumentado em servidor e SDK, trace ID propagado nos headers (W3C Trace Context), exports pra Tempo, Honeycomb ou Datadog dependendo do que o cliente já usa. Métricas RED (Rate, Errors, Duration) por endpoint, alertas em SLO (99% das chamadas em menos de 200ms, por exemplo). Quando um parceiro reclama de lentidão, abrimos o trace e mostramos onde está — sem chute.
Stack que usamos em produção hoje
Framework: Hono pra APIs públicas com TypeScript, schemas Zod e geração de OpenAPI via `@hono/zod-openapi`. Express ou Fastify quando o cliente já tem ecossistema rodando — não forçamos mudança de framework sem motivo. Next.js Route Handlers quando a API é interna do produto e compartilha auth/middleware com a app.
GraphQL: usamos quando o caso justifica (cliente mobile/web consumindo grafo de dados ricos, evolução frequente do schema). Apollo Server self-hosted ou Pothos com Yoga. GraphQL é poderoso mas custa em complexidade de cache, rate limit por query e autorização granular — REST simples vence em 70% dos casos.
Persistência e cache: Postgres + Prisma pra estado autoritativo, Redis pra cache idempotente (TTL curto, invalidação por evento), Outbox pattern em Postgres pra publicação eventual em Kafka/SQS quando o sistema vira event-driven.
Webhooks: receivers com validação HMAC de signature, fila BullMQ pra processamento assíncrono (resposta 200 em menos de 1s sempre), retry exponencial com dead-letter queue após N falhas. Emissores próprios com mesma lógica — entrega garantida, idempotência no consumidor.
Deploy: Coolify ou Kubernetes dependendo do stack do cliente. API Gateway (Kong, Tyk) quando há mais de 10 APIs internas que justificam roteamento, rate limit e auth centralizados; sem gateway quando são 1-3 APIs e Nginx + middleware no app resolvem.
O que vai (e o que não vai) entregar valor
Onde nossa abordagem entrega valor: empresas que dependem de integrações com parceiros como fonte de receita ou operação (marketplace, fintech, logística), produtos que expõem API pública pra desenvolvedores (DX importa, OpenAPI bem-feito reduz tickets em 70%), e operações com volume alto de webhooks recebidos que precisam de idempotência confiável.
Onde nossa abordagem é overkill: integração ponto-a-ponto entre dois sistemas internos sem perspectiva de crescer (script direto resolve), MVP em fase de descoberta onde o contrato vai mudar a cada semana (versionar antes de estabilizar é desperdício), e times sem capacidade de operar API em produção 24/7 — recomendamos contratar SaaS de iPaaS (Workato, Tray.io) nesses casos.
Sobre microservices: só recomendamos acima de 15-20 engenheiros. Abaixo disso, monolito modular bem-feito (com domínios separados em pacotes do mesmo deploy) entrega melhor — menos overhead de rede, menos complexidade de deploy, menos tempo perdido em DevOps que não paga conta. Microservices vendem bem, mas custam caro em coordenação de equipe pequena.
Propriedade · tudo no seu nome
Os contratos OpenAPI, os SDKs gerados e o código da API ficam no seu repositório, versionados. Você é dono da camada de integração que conecta o seu negócio — sem ficar refém de quem a construiu.
Próximo passo
O diagnóstico de API é uma conversa de 30 minutos onde olhamos a API atual (ou a que você precisa construir), identificamos onde a dor está (contrato? auth? idempotência? performance?) e respondemos: refactor pontual resolve ou justifica rebuild? Quando rebuild não se paga, ajudamos a tapar buraco sem prometer revolução.
Diagnóstico técnico de API ou integração
Em 1 chamada de 30 min mapeamos sua API atual (ou o que você precisa expor), apontamos onde está a dor e sugerimos refactor ou rebuild — sem empurrar o caminho mais caro.