Design de API RESTful e Integração com WebSocket
Construindo e consumindo APIs de dados de mercado e negociação
REST: Recursos e Verbos
REST mapeia CRUD para HTTP: GET para leituras, POST para criar, PATCH para atualizações parciais, DELETE para remover. Use os códigos de status com honestidade — 200 com um JSON de erro quebra os clientes.
Versione no caminho (/v1/), pagine listas grandes (feeds por cursor para streams somente-anexação), e documente mudanças que quebram compatibilidade com uma janela de descontinuação.
Chaves e HMAC
Chaves de API identificam; segredos comprovam. Para endpoints de negociação, aplique HMAC a uma string canônica (método + caminho + corpo + timestamp) para que o segredo nunca viaje na rede. Rejeite timestamps desatualizados para bloquear ataques de repetição — ±30s é uma janela comum.
O OAuth se encaixa em aplicativos de terceiros; bots que operam diretamente na corretora geralmente ficam com chave+HMAC. Limites de taxa: espere receber 429 e respeite o Retry-After.
Upgrades de WebSocket
A sessão começa como um HTTP GET com Upgrade: websocket; o servidor retorna 101 Switching Protocols. Depois disso, os frames são baratos em comparação a handshakes TLS repetidos no polling via HTTP.
Mensagens de inscrição geralmente são JSON: método, canais e, às vezes, assinaturas de autenticação para execuções privadas.
Livros, Negociações, Recuperação
O stream de negociações é dado tick a tick; os livros são snapshot + delta com números de sequência. Se você perder sequências, resincronize a partir de um snapshot REST e depois aplique os deltas com sequência > a do snapshot.
Heartbeat: envie ping ou espere pings do servidor; reconecte com backoff com jitter (variação aleatória) para evitar avalanches de reconexão.
GraphQL e OpenAPI
O GraphQL reduz o excesso de dados buscados (over-fetching) em dashboards; muitas corretoras ainda expõem REST para os caminhos críticos de negociação. Especificações OpenAPI (Swagger) ajudam na geração de código e no QA — mantenha os exemplos prontos para copiar e colar.
Um Padrão Mínimo de Consumidor
Rode o loop do WebSocket em uma tarefa, empurre os últimos preços para um mapa thread-safe, exponha HTTP para verificações de saúde. Registre em log as contagens de reconexão; alerte quando elas dispararem.
Coloque testes de assinatura e de dessincronização de relógio na integração contínua (CI): um HMAC quebrado em produção é indistinguível de “o mercado se moveu” até você auditar os logs.