Práticas recomendadas para usar a API REST

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 obter mais informações, confira "Documentação de webhooks".

Siga qualquer redirecionamento que a API enviar para você

O GitHub é explícito ao informar quando um recurso foi movido, fornecendo um código de estado de redirecionamento. Você deveria seguir estes redirecionamentos. Cada resposta de redirecionamento define o cabeçalho Location com o novo URI a ser acessado. Se você receber um redirecionamento, é melhor atualizar seu código para seguir a nova URI, caso você esteja solicitando um caminho obsoleto que possamos remover.

Fornecemos uma lista de códigos de status HTTP que você pode consultar ao projetar seu aplicativo para seguir redirecionamentos.

Não analise as URLs manualmente

Muitas vezes, as respostas da API contêm dados na forma de URLs. Por exemplo, quando um repositório é solicitado, enviamos uma chave chamada clone_url com uma URL que você pode usar para clonar o repositório.

Para a estabilidade do seu aplicativo, você não deve tentar analisar esses dados ou tentar adivinhar e construir o formato de URLs futuras. Seu app será poderá falhar se decidirmos alterar a URL.

Por exemplo, quando você trabalha com resultados paginados, muitas vezes, é uma tentação construir URLs que acrescentam ?page=<number> ao final. Evite essa tentação. Para obter mais informações sobre como seguir resultados paginados de maneira confiável, confira "Como usar paginação na API REST".

Lidar com limites de taxa

O limite de taxa de API GitHub assegura que a API seja rápida e esteja disponível para todos.

Se você atingir um limite de taxa, deverá parar de fazer solicitações até o horário especificado pelo cabeçalho de x-ratelimit-reset. O não cumprimento pode resultar no banimento de sua integração. Para obter mais informações, confira "Recursos na API REST".

Lidando com limites de taxa secundária

GitHub também pode usar limites de taxa secundários para garantir a disponibilidade da API. Para obter mais informações, confira "Recursos na API REST".

Para evitar atingir este limite, você deverá certificar-se de que o seu aplicativo segue as diretrizes abaixo.

Faça solicitações autenticadas, ou use o ID de cliente e segredo do seu aplicativo. As solicitações não autenticadas estão sujeitas a limites de taxa secundária mais agressivos.
Faça solicitações de um único usuário ou ID de cliente em série. Não faça solicitações para um só usuário ou uma ID de cliente simultaneamente.
Se estiver fazendo um grande número de solicitações POST, PATCH, PUT ou DELETE para um só usuário ou ID de cliente, aguarde, pelo menos, um segundo entre cada solicitação.
Quando você tiver sido limitado, aguarde antes de tentar novamente sua solicitação.
- Se o cabeçalho de resposta Retry-After estiver presente, tente novamente sua solicitação após o tempo especificado no cabeçalho. O valor do cabeçalho Retry-After será sempre um inteiro, representando o número de segundos que você deve esperar antes de fazer solicitações novamente. Por exemplo, Retry-After: 30 significa que você deve esperar 30 segundos antes de enviar mais solicitações.
- Se o cabeçalho de x-ratelimit-remaining for 0, você deverá repetir sua solicitação após o tempo especificado pelo cabeçalho de x-ratelimit-reset. O cabeçalho x-ratelimit-reset sempre é um inteiro que representa o tempo em que a janela de limite de taxa atual é redefinida em segundos de época UTC.
- Caso contrário, aguarde uma quantidade exponencialmente crescente de tempo entre as novas tentativas e gere um erro após um número específico de tentativas.

GitHub reserva-se o direito de alterar essas diretrizes conforme necessário para garantir a disponibilidade.

Lidar com erros da API

Embora o seu código nunca introduzisse um erro, você pode descobrir que encontrou erros sucessivos ao tentar acessar a API.

Em vez de ignorar os códigos de status repetidos 4xx e 5xx, você deverá verificar se 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 5xx e a chamada não terá sucesso. 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.