Como projetar um SDK sobre uma API HTTP

Objetivo

Entregar uma biblioteca cliente que permita a quem integra, seja pessoa ou agente, usar a API sem precisar ler os detalhes de HTTP, sem esconder a semântica da API e sem que o SDK se torne uma segunda API a manter.

Pré-requisitos

Uma descrição da API legível por máquina (OpenAPI ou protobuf) que seja a única fonte de verdade; uma política de versionamento da API; uma decisão sobre quais linguagens suportar primeiro, com base em quem faz a integração.

Passos

1. Gere a camada de transporte (modelos, serialização, chamadas de endpoints) a partir da descrição; nunca mantenha à mão o que a descrição já declara. Mantenha o código gerado em um pacote ou diretório próprio, para que o código escrito à mão sobreviva à regeneração.
2. Adicione um objeto cliente que concentre a configuração: URL base, credenciais, timeouts, política de retentativas e um user agent que informe a versão do SDK. Leia as credenciais primeiro dos parâmetros e depois das variáveis de ambiente; não invente arquivos de configuração.
3. Mapeie os erros HTTP para um único tipo de exceção ou de resultado, que traga o status, o corpo de erro da API, o identificador da requisição e a indicação de se o erro admite nova tentativa. Não lance tipos diferentes por endpoint.
4. Implemente as retentativas uma única vez, no transporte: apenas para chamadas idempotentes ou que levem uma chave de idempotência gerada pelo SDK; use backoff exponencial com jitter; respeite Retry-After; limite o tempo total.
5. Encapsule a paginação em um iterador que busca as páginas sob demanda e exponha a chamada de página bruta para quem precisa de mais controle.
6. Encapsule as operações de longa duração em um auxiliar de espera que faz polling conforme as indicações do servidor e um prazo limite, e devolve o resultado ou o erro da operação.
7. Versione o SDK independentemente da API, com versionamento semântico: a versão maior do SDK muda quando a sua própria interface quebra, não quando a API acrescenta um campo.
8. Teste contra um servidor gravado ou de sandbox na CI e, periodicamente, contra o sandbox real; publique um changelog que indique a versão da API visada por cada release do SDK.
9. Escreva o README como um tutorial da primeira chamada: instalar, configurar, uma chamada, um erro tratado; remeta todo o resto à referência da API.

Resultado esperado

Quem integra escreve menos linhas e encontra menos bugs de retentativa e de paginação, e o comportamento do SDK corresponde à semântica documentada da API, porque a maior parte dele é gerada.

Limites e base de verificação

É um protocolo proposto; não se afirma nenhuma comparação entre designs de SDK. Os recursos de conveniência escritos à mão (builders, auxiliares que combinam várias chamadas) são onde os SDKs se afastam da API; mantenha-os enxutos e identifique-os na documentação como conveniências.