Evitar sondagens
Você deve assinar eventos de webhook em vez de sondar a API para obter dados. Isso ajudará sua integração a permanecer dentro do limite de fluxo da API. Para saber mais, confira Documentação de webhooks.
Fazer solicitações autenticadas
As solicitações autenticadas têm uma limitação de fluxo primária mais alta do que as solicitações não autenticadas. Para evitar exceder a limitação de fluxo, você deve fazer solicitações autenticadas. Para saber mais, confira Limites de taxa para a API REST.
Evitar solicitações simultâneas
Para evitar exceder as limitações de fluxo secundárias, você deve fazer solicitações em série em vez de simultaneamente. Para conseguir isso, você pode implementar um sistema de filas para solicitações.
Pausar entre solicitações mutativas
Se estiver fazendo um grande número de solicitações POST, PATCH, PUT ou DELETE, aguarde, pelo menos, um segundo entre cada solicitação. Isso ajudará você a evitar limitações de fluxo secundárias.
Lidar com erros de limitação de fluxo adequadamente
Se você receber um erro de limitação de fluxo, deverá parar de fazer solicitações temporariamente, de acordo com estas diretrizes:
- Se o cabeçalho de resposta
retry-afterestiver presente, você não deverá repetir sua solicitação até que esse número de segundos tenha decorrido. - Se o cabeçalho de
x-ratelimit-remainingfor0, você não deverá repetir sua solicitação até depois do horário especificado pelo cabeçalho dex-ratelimit-reset. O cabeçalhox-ratelimit-resetestá em segundos de época UTC. - Caso contrário, aguarde pelo menos um minuto antes de tentar novamente. Se sua solicitação continuar falhando devido a uma limitação de fluxo secundário, aguarde um período de tempo exponencialmente crescente entre as tentativas e lance um erro após um número específico de tentativas.
Continuar a fazer solicitações enquanto você está com limitação de fluxo pode resultar no banimento de sua integração.
Seguir redirecionamentos
A API REST do GitHub usa o redirecionamento HTTP quando apropriado. Você deve assumir que qualquer solicitação pode resultar em um redirecionamento. Receber um redirecionamento de HTTP não é um erro e você deve seguir esse redirecionamento.
Um código de status 301 indica redirecionamento permanente. Você deve repetir sua solicitação para a URL especificada pelo cabeçalho location. Além disso, você deve atualizar seu código para usar essa URL para solicitações futuras.
Um código de status302 ou 307 indica o redirecionamento temporário. Você deve repetir sua solicitação para a URL especificada pelo cabeçalho location. No entanto, você não deve atualizar seu código para usar essa URL para solicitações futuras.
Outros códigos de status de redirecionamento podem ser usados de acordo com a especificação HTTP.
Não analisar URLs manualmente
Muitos pontos de extremidade de API retornam valores de URL para campos no corpo da resposta. Você não deve tentar analisar essas URLs ou prever a estrutura de URLs futuras. Isso pode fazer com que sua integração seja interrompida se GitHub alterar a estrutura da URL no futuro. Em vez disso, você deve procurar um campo que contenha as informações necessárias. Por exemplo, o ponto de extremidade para criar um problema retorna um campo html_urlcom um valor como https://github.com/octocat/Hello-World/issues/1347 e um campo number com um valor como 1347. Se você precisar saber o número do problema, use o campo number em vez de analisar o campo html_url.
Da mesma forma, você não deve tentar construir manualmente consultas de paginação. Em vez disso, você deve usar os cabeçalhos de link para determinar quais páginas de resultados você pode solicitar. Para saber mais, confira Como usar paginação na API REST.
Use solicitações condicionais, se apropriado
A maioria dos pontos de extremidade retorna um cabeçalho etag e muitos pontos de extremidade retornam um cabeçalho last-modified. Você pode usar os valores desses cabeçalhos para fazer solicitações condicionais. Se a réplica não tiver sido alterada, você receberá uma réplica 304 Not Modified. Fazer uma solicitação condicional não conta para o limite de limitação de fluxo se uma réplica 304 for retornada.
Por exemplo, se uma solicitação anterior retornou um valor de cabeçalho etag de 644b5b0155e6404a9cc4bd9d8b1ae730, você poderá usar o cabeçalho if-none-match em uma solicitação futura:
curl https://api.github.com/meta --include --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
Por exemplo, se uma solicitação anterior retornou um valor de cabeçalho last-modified de Wed, 25 Oct 2023 19:17:59 GMT, você poderá usar o cabeçalho if-modified-since em uma solicitação futura:
curl https://api.github.com/repos/github/docs --include --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT'
Não ignore erros
Você não deve ignorar códigos de erro 4xx e 5xx repetidos. Em vez disso, você deve garantir que está interagindo corretamente com a API. Por exemplo, se um ponto de extremidade solicitar uma cadeia de caracteres e você estiver transmitindo a ela um valor numérico, você receberá um erro de validação. Da mesma forma, a tentativa de acessar um ponto de extremidade não autorizado ou inexistente, vai gerar um erro 4xx.
Ignorar intencionalmente erros de validação repetidos pode resultar na suspensão do seu aplicativo por abuso.