{"meta":{"title":"Práticas recomendadas para usar a API REST","intro":"Siga estas práticas recomendadas ao usar a API do GitHub.","product":"API REST","breadcrumbs":[{"href":"/pt/rest","title":"API REST"},{"href":"/pt/rest/using-the-rest-api","title":"Usando a API REST"},{"href":"/pt/rest/using-the-rest-api/best-practices-for-using-the-rest-api","title":"Práticas recomendadas"}],"documentType":"article"},"body":"# Práticas recomendadas para usar a API REST\n\nSiga estas práticas recomendadas ao usar a API do GitHub.\n\n## Evitar sondagens\n\nVocê 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](/pt/webhooks).\n\nSe 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:\n\n* 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.\n* 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](#use-conditional-requests).\n* 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](#make-requests-that-can-be-cached).\n\n## Fazer solicitações autenticadas\n\nAs 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](/pt/rest/using-the-rest-api/rate-limits-for-the-rest-api).\n\n## Evitar solicitações simultâneas\n\nPara 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.\n\n## Pausar entre solicitações mutativas\n\nSe 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.\n\n## Lidar adequadamente com erros de limitação de taxa\n\nSe você receber um erro de limitação de fluxo, deverá parar de fazer solicitações temporariamente, de acordo com estas diretrizes:\n\n* 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.\n* 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.\n* 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.\n\nContinuar a fazer solicitações enquanto você está sob limitação de taxa pode resultar no bloqueio da sua integração.\n\n## Seguir redirecionamentos\n\nA 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.\n\nUm 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.\n\nUm código de status`302` 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.\n\nOutros códigos de status de redirecionamento podem ser usados de acordo com a especificação HTTP.\n\n## Não analisar URLs manualmente\n\nMuitos 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_url`com 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`.\n\nDa 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](/pt/rest/using-the-rest-api/using-pagination-in-the-rest-api).\n\n## Usar solicitações condicionais\n\nA 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.\n\nNos exemplos a seguir, substitua `YOUR-TOKEN` pelo token de acesso.\n\nPara fazer uma solicitação condicional com um `etag`:\n\n1. Faça uma solicitação e salve o valor do `etag` cabeçalho da resposta.\n\n   ```shell\n   curl --include --header \"Authorization: Bearer YOUR-TOKEN\" https://api.github.com/repos/octocat/Spoon-Knife/pulls\n   ```\n\n   A resposta inclui um `etag` cabeçalho:\n\n   ```text\n   HTTP/2 200\n   etag: \"644b5b0155e6404a9cc4bd9d8b1ae730\"\n   ```\n\n2. Em sua próxima solicitação para a mesma URL, envie o valor salvo no cabeçalho `if-none-match`.\n\n   ```shell\n   curl --include --header \"Authorization: Bearer YOUR-TOKEN\" --header 'if-none-match: \"644b5b0155e6404a9cc4bd9d8b1ae730\"' https://api.github.com/repos/octocat/Spoon-Knife/pulls\n   ```\n\n   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:\n\n   ```text\n   HTTP/2 304\n   ```\n\nVocê 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:\n\n```shell\ncurl --include --header \"Authorization: Bearer YOUR-TOKEN\" --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT' https://api.github.com/repos/octocat/Spoon-Knife\n```\n\nSolicitaçõ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.\n\n## Fazer solicitações que podem ser armazenadas em cache\n\nUma 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.\n\nSolicite 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 `&`:\n\n```shell\ncurl --include --header \"Authorization: Bearer YOUR-TOKEN\" \"https://api.github.com/repos/octocat/Spoon-Knife/pulls?head=HEAD-OWNER:BRANCH-NAME\"\n```\n\nAo 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.\n\nUse 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\n## Não ignore erros\n\nVocê 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`.\n\nSe 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.\nGitHub 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](/pt/rest/using-the-rest-api/troubleshooting-the-rest-api#404-not-found-for-an-existing-resource). 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.\n\nIgnorar intencionalmente erros de validação repetidos pode resultar na suspensão do seu aplicativo por abuso.\n\n## Leitura adicional\n\n* [Melhores práticas para usar webhooks](/pt/webhooks/using-webhooks/best-practices-for-using-webhooks)\n* [Práticas recomendadas para criar um aplicativo GitHub](/pt/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app)"}