Melhores Práticas para o SDK de Cliente de API

Gere o cliente de baixo nível a partir de uma especificação OpenAPI, e escreva manualmente apenas uma camada fina e idiomática por cima. Confiança: 0.85 Trate a especificação da API como a fonte da verdade e falhe o CI quando o código gerado estiver desatualizado. Confiança: 0.85 Torne a primeira chamada possível em três linhas: instalar, criar um cliente com uma chave de API, chamar um método. Confiança: 0.90 Leia a chave de API de uma variável de ambiente bem conhecida por padrão, e nunca a registre em logs ou a inclua em mensagens de erro. Confiança: 0.95 Exponha modelos de requisição e resposta totalmente tipados, com tipos TypeScript ou dicas de tipo Python incluídos no pacote. Confiança: 0.90 Retorne erros tipados com o status HTTP, código de erro, mensagem e ID da requisição, em vez de uma exceção genérica. Confiança: 0.90 Repita requisições idempotentes em timeouts, respostas 429 e 5xx com backoff exponencial e jitter, e respeite os cabeçalhos Retry-After. Confiança: 0.90 Envie uma chave de idempotência automaticamente em requisições POST repetidas quando a API suportar isso. Confiança: 0.80 Defina timeouts padrão sensatos e permita que os chamadores substituam as configurações de timeout e repetição por cliente e por requisição. Confiança: 0.85 Forneça iteradores com paginação automática para que os usuários possam percorrer todos os resultados sem lidar com cursores manualmente. Confiança: 0.85 Suporte respostas em streaming com iteradores assíncronos nativos ou geradores, em vez de callbacks. Confiança: 0.80 Ofereça clientes síncronos e assíncronos em linguagens onde ambos são comuns, compartilhando os mesmos modelos. Confiança: 0.75 Mantenha as dependências de runtime mínimas e evite fixar os usuários a uma versão específica de biblioteca HTTP. Confiança: 0.85 Envie um cabeçalho User-Agent com o nome do SDK, versão e runtime para que os proprietários da API possam ver a adoção e depurar problemas. Confiança: 0.80 Siga o versionamento semântico estritamente e documente mudanças que quebram com exemplos de migração no changelog. Confiança: 0.90 Nunca remova um método em uma versão menor; deprecie-o com um aviso primeiro. Confiança: 0.85 Teste contra fixtures HTTP gravados para velocidade e execute uma suíte menor contra um ambiente sandbox real diariamente. Confiança: 0.80 Execute a suíte de testes em todas as versões de runtime suportadas no CI, como cada versão LTS ativa do Node.js ou versão do Python. Confiança: 0.85 Coloque exemplos de código executáveis no README e na documentação, e teste esses exemplos no CI para que nunca fiquem desatualizados. Confiança: 0.80 Exponha hooks ou middleware para logging, rastreamento e cabeçalhos personalizados, em vez de adicionar opções pontuais para cada necessidade. Confiança: 0.75 Permita uma URL base personalizada e um cliente HTTP personalizado para que os usuários possam apontar o SDK para proxies, mocks ou endpoints regionais. Confiança: 0.80 Publique pacotes a partir do CI com proveniência e releases assinados, nunca a partir do laptop de um mantenedor. Confiança: 0.75