Como integrar uma API REST com segurança
Um roteiro para entender autenticação, requisições HTTP, paginação, erros e retentativas antes de levar sua integração para produção.
Comece pelo contrato da API
Antes de escrever código, defina a ação que a integração precisa realizar. Liste os recursos envolvidos, as permissões necessárias e o dado que confirma o sucesso. Na documentação oficial, confira a URL base, a versão, o formato do corpo e os limites do serviço. Um exemplo de outra versão pode funcionar de forma diferente.
REST é um estilo de arquitetura; JSON é um formato de dados. Uma API apresentada como REST pode receber formulários, retornar outros formatos ou aplicar convenções próprias. Registre essas diferenças no projeto e escolha um ambiente de teste quando o provedor oferecer esse recurso.
Proteja as credenciais e limite o acesso
Identifique o mecanismo exigido pelo provedor: chave de API, token de acesso, OAuth ou outro. Use a credencial específica do ambiente e solicite apenas o acesso necessário para a operação. Confira o nome do cabeçalho na referência: Authorization não é uma convenção universal para todas as chaves.
Credenciais secretas devem ficar no servidor, em variáveis de ambiente ou em um gerenciador de segredos. Evite incluí-las no código publicado, no JavaScript enviado ao navegador e nos logs. Em uma aplicação com várias empresas, associe cada conexão ao cliente correto antes de executar a chamada.
Entenda métodos e respostas HTTP
GET consulta um recurso. POST normalmente solicita a criação ou execução de uma operação. PUT e DELETE têm semântica idempotente no HTTP: repetir a mesma requisição deve preservar o efeito pretendido. Isso não significa que todas as respostas serão iguais, nem que uma operação pode ser repetida sem ler o contrato do provedor.
Verifique o status antes de interpretar o corpo. Respostas 2xx indicam sucesso HTTP; uma resposta 204 não contém corpo. Erros 4xx costumam exigir correção da requisição ou das permissões. Falhas 5xx podem ser transitórias. APIs GraphQL e algumas APIs HTTP também podem informar falhas dentro de uma resposta 200.
Faça uma primeira chamada controlada
O exemplo abaixo consulta um repositório público do GitHub em Node.js moderno. Ele limita a espera, verifica o status HTTP e confirma o tipo do conteúdo. Para outra API, substitua a URL e os cabeçalhos conforme a referência oficial; o padrão de validação continua útil.
fetch não rejeita automaticamente a promessa quando o servidor retorna um erro HTTP. Trate response.ok explicitamente. Valide também os campos necessários do JSON antes de gravá-los no banco: uma resposta válida em JSON ainda pode ter um formato diferente do esperado.
const response = await fetch(
'https://api.github.com/repos/octocat/Hello-World',
{
headers: { Accept: 'application/vnd.github+json' },
signal: AbortSignal.timeout(10_000)
}
);
if (!response.ok) {
throw new Error('Falha HTTP: ' + response.status);
}
const contentType = response.headers.get('content-type') || '';
if (!contentType.includes('application/json')) {
throw new Error('Resposta fora do formato esperado');
}
const repository = await response.json();
if (typeof repository.full_name !== 'string') {
throw new Error('Repositório sem o campo full_name');
}
console.log(repository.full_name);Planeje paginação e retentativas
Uma lista raramente contém todos os registros em uma chamada. Siga os links ou cursores devolvidos pela API e mantenha os filtros durante a paginação. Para uma sincronização longa, salve o progresso de forma que uma falha permita continuar sem reprocessar toda a base.
Ao receber 429, respeite as orientações de limite e o cabeçalho Retry-After quando disponível. Adote um número máximo de tentativas e intervalos crescentes com variação aleatória para falhas transitórias. Antes de repetir uma escrita após um timeout, confirme se ela já foi aplicada. Use uma chave de idempotência apenas quando a API documentar esse suporte.
Valide o comportamento antes da produção
Teste sucesso, credencial inválida, permissão insuficiente, resposta vazia, paginação e tempo limite. Para operações que alteram dados, inclua o caso em que a conexão cai depois de o provedor concluir a ação. O resultado esperado deve ser definido pelo negócio, como criar exatamente um pedido.
Registre o status, a duração, a operação e o identificador de requisição do provedor, quando existir. Remova tokens e dados pessoais desnecessários dos registros. Acompanhe falhas por integração e mantenha uma rotina de revisão do changelog para antecipar mudanças de versão.
Fontes e referências oficiais
Consulte o contrato e as recomendações da plataforma que você está integrando. Os detalhes variam por serviço e podem evoluir.