Práticas recomendadas para usar a API REST

Evitar sondagens

Você deve assinar eventos de webhook em vez de interrogar 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.

Se você não pode usar webhooks e deve sondar a API, faça a sondagem da maneira mais eficiente possível para evitar exceder o limite de taxa:

• Sondar apenas quantas vezes você precisar, em um agendamento fixo. Se uma resposta incluir um x-poll-interval cabeçalho, aguarde pelo menos tantos segundos antes de sondar o mesmo ponto de extremidade novamente.
• Faça solicitações condicionais autenticadas, para que os dados inalterados não contem em relação ao limite de taxa primária. Para obter mais informações, consulte Usar solicitações condicionais.
• Solicite apenas os dados de que você precisa e mantenha as respostas estáveis, para que mais de suas consultas retornem 304 Not Modified. Para obter mais informações, consulte Fazer solicitações que podem ser armazenadas em cache.

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 o limite de taxa, 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 taxa secundárias, você deve fazer solicitações em série, em vez de concorrentemente. 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 limites de taxa secundários.

Lidar adequadamente com erros de limitação de taxa

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-after estiver 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-remaining for 0, você não deverá repetir sua solicitação até depois do horário especificado pelo cabeçalho de x-ratelimit-reset. O cabeçalho x-ratelimit-reset está 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 taxa secundária, aguarde um período de tempo exponencialmente crescente entre as tentativas e lance um erro depois de um número específico de tentativas.

Continuar a fazer solicitações enquanto você está sob limitação de taxa pode resultar no bloqueio da sua integração.

Seguir redirecionamentos

A GitHub API REST 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.

Usar solicitações condicionais

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 GET condicionais. Se a resposta não tiver sido alterada, você receberá uma resposta 304 Not Modified. Fazer uma solicitação condicional não é contabilizada contra o limite principal de taxa se uma resposta 304 for retornada e a solicitação for feita com a devida autorização em um cabeçalho Authorization. Isso torna as solicitações condicionais especialmente úteis quando você sonda um ponto de extremidade, pois cada 304 Not Modified resposta é rápida e não usa o limite de taxa.

Nos exemplos a seguir, substitua YOUR-TOKEN pelo token de acesso. Substitua REPO-OWNER pela conta que possui o repositório e substitua REPO-NAME pelo nome do repositório.

Para fazer uma solicitação condicional com um etag:

1. Faça uma solicitação e salve o valor do etag cabeçalho da resposta.

   curl --include --header "Authorization: Bearer YOUR-TOKEN" http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/pulls
   

   A resposta inclui um etag cabeçalho:

   HTTP/2 200
   etag: "644b5b0155e6404a9cc4bd9d8b1ae730"
   

2. Em sua próxima solicitação para a mesma URL, envie o valor salvo no cabeçalho if-none-match.

   curl --include --header "Authorization: Bearer YOUR-TOKEN" --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"' http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/pulls
   

   Se os dados não tiverem sido alterados, você receberá uma 304 Not Modified resposta, que não conta em relação ao limite de taxa primária:

   HTTP/2 304
   

Você também pode usar o last-modified cabeçalho. 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 --include --header "Authorization: Bearer YOUR-TOKEN" --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT' http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME

Solicitações condicionais para métodos não seguros, como POST, PUT, PATCH e DELETE não são compatíveis, a menos que seja descrito de outra forma na documentação de um ponto de extremidade específico.

Fazer solicitações que podem ser armazenadas em cache

Uma solicitação condicional só economiza tempo e limite de taxa se o ponto de extremidade retornar 304 Not Modified. O endpoint retorna 304 quando a representação que você solicitou não foi alterada desde que você salvou o valor de etag ou de last-modified dela; cabeçalhos de resposta não relacionados, como a data, podem ainda diferir. Para aumentar a probabilidade de obter respostas 304 ao fazer consultas, mantenha suas requisições estáveis e específicas.

Solicite apenas os dados necessários. Uma resposta menor e mais específica muda com menos frequência, de modo que retorna 304 Not Modified com mais frequência. Por exemplo, para verificar as solicitações de pull de um branch, filtre a lista por esse branch em vez de listar cada solicitação de pull e pesquisar os resultados por conta própria. Substitua HEAD-OWNER pela conta que possui o branch principal; para uma solicitação de pull de uma bifurcação, essa é a conta que possui a bifurcação. Substitua BRANCH-NAME pelo nome da ramificação e codifique-o em URL se ele contiver caracteres especiais, como # ou &:

curl --include --header "Authorization: Bearer YOUR-TOKEN" "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/pulls?head=HEAD-OWNER:BRANCH-NAME"

Ao paginar uma lista, use uma ordenação estável. Alguns parâmetros, como sort=updated, reordenam a lista sempre que um item é alterado. Quando um item passa para uma nova posição, os itens entre suas posições antigas e novas mudam para páginas diferentes, de modo que as páginas que você já buscaram podem retornar novos dados em vez de 304 Not Modified. Uma ordem estável, como o padrão, impede que as atualizações para itens existentes reordenem a lista, embora adicionar ou remover itens ainda possa transferir entradas para outras páginas.

Use os mesmos parâmetros sempre que consultar os mesmos dados. Um tamanho da página diferente, um número de página ou um filtro produzem uma resposta diferente com um etag diferente.

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 endpoint solicitar uma cadeia de caracteres e você estiver passando um valor numérico, receberá um erro de validação. Da mesma forma, a tentativa de acessar um endpoint não autorizado ou inexistente vai gerar um erro 4xx.

Se você estiver sondando e um recurso retornar repetidamente uma 404 Not Found resposta, não continue solicitando-a em todas as pesquisas. Primeiro, certifique-se de que o 404 não seja causado por problemas de autenticação ou autorização. GitHub retorna uma 404 Not Found resposta em vez de uma 403 Forbidden resposta para alguns recursos privados quando suas credenciais não concedem acesso, portanto 404 , nem sempre significa que o recurso está ausente. Para saber mais, confira Solucionar problemas do API REST. Depois de confirmar que suas credenciais estão corretas, aguarde muito mais tempo antes de verificar novamente ou verifique novamente somente quando você tiver um motivo para acreditar que o recurso agora existe. Solicitar repetidamente um recurso ausente desperdiça seu limite de taxa e pode disparar um limite de taxa secundário.

Ignorar intencionalmente erros de validação repetidos pode resultar na suspensão do seu aplicativo por abuso.

Leitura adicional

• Melhores práticas para usar webhooks
• Práticas recomendadas para criar um aplicativo GitHub