Definição de API: o que é
A definição de API é o contrato documentado que descreve como um cliente deve chamar uma API e como a API responderá. Ela normalmente inclui rotas de endpoint, formatos de solicitação/resposta (por exemplo, campos JSON), tipos de dados, parâmetros obrigatórios vs. opcionais, autenticação e permissões, limites de taxa, formatos de erro e quaisquer expectativas declaradas de tempo ou ordenação.
Em um contexto de negociação automatizada, a definição de API é importante porque cada etapa downstream—ingestão de dados, lógica de sinais, decisões de execução e relatórios—depende do que a API garante versus o que ela meramente “tenta” fornecer. O principal objetivo da avaliação é entender quais partes são mecânica estável e quais partes podem variar com as condições de mercado, carga do sistema e políticas do provedor.
Como verificar uma definição de API (checklist objetiva)
- Completude do contrato (pontos de verificação)
- Endpoints e métodos estão explicitamente listados.
- Esquemas de solicitação e resposta estão definidos, incluindo significados de campos e tipos de dados.
- Existem exemplos para respostas normais e para cada tipo de erro documentado.
- Requisitos de autenticação e autorização estão declarados (por exemplo, como as credenciais são fornecidas e qual acesso é permitido).
- Detalhes de comportamento (a parte “como funciona”)
- Confirme se a API define ordenação ou consistência entre chamadas (por exemplo, se “mais recente” está vinculado a um carimbo de data/hora).
- Verifique como os carimbos de data/hora são representados (formato, fuso horário e se refletem o tempo do evento ou o tempo de processamento).
- Verifique como funcionam paginação, filtragem e limites, incluindo tamanhos máximos de página e valores padrão.
- Condições variáveis vs. mecânica estável
- Separe elementos estáveis (esquema, regras de parâmetros, códigos de erro documentados) de elementos variáveis (latência, lacunas nos dados, movimento do mercado, limitação devido à carga).
- Trate qualquer declaração sobre “tempo real” ou “streaming” como uma afirmação comportamental que você deve verificar por meio de testes ou respostas de amostra, não como uma promessa fixa.
- Evidências e prova documental Procure artefatos de implementação que permitam validar o contrato:
- Documentação que inclua payloads de amostra e respostas de erro.
- Política de versionamento que descreva como as mudanças são introduzidas e por quanto tempo versões antigas permanecem suportadas.
- Recursos de teste, como ambientes sandbox, endpoints simulados ou chamadas de exemplo gravadas.
- Declarações claras de limitação (bandeiras vermelhas) Identifique lacunas onde a documentação é silenciosa ou ambígua:
- Definições ausentes para campos críticos.
- Semântica de erro pouco clara (por exemplo, se um erro é repetível).
- Nenhuma descrição de backpressure, comportamento de limite de taxa ou o que acontece durante interrupções parciais.
Evidências ou exemplo: o que “verificação” significa
Um exemplo prático de avaliação baseada em evidências é executar chamadas scriptadas que cubram:
- Uma solicitação de “caminho feliz” e confirmar que os campos de resposta correspondem ao esquema documentado.
- Pelo menos uma condição de limite, como um parâmetro inválido que deve acionar um erro documentado.
- Uma verificação de latência/tempo medindo o tempo de ida e volta e comparando-o com quaisquer expectativas de tempo declaradas.
Exemplo de suposição (declare-o explicitamente): se você medir o tempo de resposta a partir do relógio do seu próprio sistema, você assume que seu relógio está razoavelmente sincronizado. Sem essa suposição, comparações de tempo podem ser enganosas.
Limitações e modos de falha a considerar
No mínimo, avalie pelo menos um modo de falha material:
- Lacunas de dados: a API pode retornar histórico incompleto, eventos ausentes ou atualizações atrasadas.
- Problemas de latência e ordenação: mesmo que existam carimbos de data/hora, a ordem das chamadas pode não corresponder à ordem dos eventos.
- Limite de taxa ou limitação: solicitações excessivas podem levar a atrasos ou erros estruturados.
- Desvio de esquema: versões de API podem alterar campos, tipos ou parâmetros obrigatórios.
- Falhas de autenticação/permissão: tokens podem expirar ou escopos de acesso podem diferir por ambiente.
Relações históricas não estabelecem resultados futuros. Mesmo que as respostas de amostra pareçam consistentes, o comportamento futuro pode mudar quando o provedor atualiza serviços ou quando a carga do sistema e a volatilidade do mercado mudam. Os resultados também variam com custos, método de execução e jurisdição, portanto, trate a definição de API como uma descrição de contrato, não como uma garantia de desempenho.
Critérios de verificação e próximas perguntas
Use um “critério de conclusão” claro antes de integrar:
- Você pode mapear cada parâmetro obrigatório e cada campo retornado para um significado documentado.
- Você pode reproduzir respostas de sucesso e erro documentadas em um ambiente de teste.
- Você documentou suposições para tempo, repetições e completude dos dados.
- Você tem um plano para lidar com limites de taxa, campos desconhecidos e mudanças de versão.
Próximas perguntas a fazer durante a avaliação:
- Qual é exatamente o modelo de consistência documentado da API para carimbos de data/hora e ordenação? - Quais erros são repetíveis e qual orientação de backoff é fornecida?