{"meta":{"title":"Como usar paginação na API REST","intro":"Saiba como navegar pelas respostas paginadas da API REST.","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/using-pagination-in-the-rest-api","title":"Paginação"}],"documentType":"article"},"body":"# Como usar paginação na API REST\n\nSaiba como navegar pelas respostas paginadas da API REST.\n\n## Sobre paginação\n\nQuando uma resposta da API REST incluir muitos resultados, GitHub paginará os resultados e retornará um subconjunto dos resultados. Por exemplo, `GET /repos/octocat/Spoon-Knife/issues` retornará apenas 30 problemas do repositório `octocat/Spoon-Knife`, embora o repositório inclua mais de 1600 problemas abertos. Isso facilita o manuseio da resposta tanto para os servidores quanto para as pessoas.\n\nVocê pode usar o cabeçalho de `link` da resposta para solicitar páginas adicionais de dados. Se um ponto de extremidade oferecer suporte ao parâmetro de consulta `per_page`, você poderá controlar quantos resultados são retornados em uma página.\n\nEste artigo demonstra como solicitar páginas adicionais de resultados para respostas paginadas, como alterar o número de resultados retornados em cada página e como escrever um script para buscar várias páginas de resultados.\n\n## Como usar cabeçalhos de `link`\n\nQuando uma resposta for paginada, os cabeçalhos de resposta incluirão um cabeçalho de `link`. O cabeçalho `link` será omitido se o ponto de extremidade não der suporte à paginação ou se todos os resultados couberem em uma única página.\n\nO cabeçalho de `link` contém URLs que você pode usar para buscar páginas adicionais de resultados. Por exemplo, a página de resultados anterior, a seguinte, a primeira, e a última.\n\nPara ver os cabeçalhos de resposta de um ponto de extremidade específico, você pode usar curl, GitHub CLI ou uma biblioteca que você está usando para fazer solicitações. Para ver os cabeçalhos de resposta se você estiver usando uma biblioteca para fazer solicitações, siga a documentação dessa biblioteca. Para ver os cabeçalhos de resposta se você estiver usando curl ou GitHub CLI, passe o sinalizador `--include` com sua solicitação. Por exemplo:\n\n```shell\ncurl --include --request GET \\\n--url \"https://api.github.com/repos/octocat/Spoon-Knife/issues\" \\\n--header \"Accept: application/vnd.github+json\"\n```\n\nSe a resposta for paginada, o cabeçalho de `link` terá esta aparência:\n\n```http\nlink: ; rel=\"prev\", ; rel=\"next\", ; rel=\"last\", ; rel=\"first\"\n```\n\nO cabeçalho de `link` fornece a URL para a página anterior, a seguinte, a primeira e a última página de resultados:\n\n* A URL da página anterior é seguida por `rel=\"prev\"`.\n* A URL da próxima página é seguida por `rel=\"next\"`.\n* A URL da última página é seguida por `rel=\"last\"`.\n* A URL da primeira página é seguida por `rel=\"first\"`.\n\nEm alguns casos, apenas um subconjunto desses links está disponível. Por exemplo, o link para a página anterior não será incluído se você estiver na primeira página de resultados e o link para a última página não será incluído se não puder ser calculado.\n\nVocê pode usar as URLs do cabeçalho de `link` para solicitar outra página de resultados. Por exemplo, para solicitar a última página de resultados com base no exemplo anterior:\n\n```shell\ncurl --include --request GET \\\n--url \"https://api.github.com/repositories/1300192/issues?page=515\" \\\n--header \"Accept: application/vnd.github+json\"\n```\n\nAs URLs no cabeçalho de `link` usam parâmetros de consulta para indicar qual página de resultados retornar. Os parâmetros de consulta nas URLs de `link` podem ser diferentes entre pontos de extremidade. No entanto, cada ponto de extremidade paginado usará os parâmetros de consulta `page`, `before`/`after` ou `since`. (Alguns endpoints usam o parâmetro `since` para algo diferente de paginação). Em todos os casos, você pode usar as URLs no cabeçalho `link` para buscar páginas adicionais de resultados. Para obter mais informações sobre parâmetros de consulta, confira [Introdução à API REST](/pt/rest/using-the-rest-api/getting-started-with-the-rest-api#query-parameters).\n\n## Como alterar o número de itens por página\n\nSe um ponto de extremidade der suporte ao parâmetro de consulta `per_page`, você poderá controlar quantos resultados são retornados em uma página. Para obter mais informações sobre parâmetros de consulta, confira [Introdução à API REST](/pt/rest/using-the-rest-api/getting-started-with-the-rest-api#query-parameters).\n\nPara a maioria dos pontos de `per_page` extremidade, o valor máximo é `100`. Se você especificar um valor maior que o máximo, GitHub não retornará um erro. Em vez disso, o valor é automaticamente reduzido ao máximo e a resposta não inclui mais do que o número máximo de resultados por página. Como a solicitação ainda é bem-sucedida, você pode receber menos resultados do que o esperado sem qualquer indicação de que o `per_page` valor foi reduzido. Para confirmar os valores padrão e máximo `per_page` para um ponto de extremidade, consulte a documentação de referência para esse ponto de extremidade.\n\nPor exemplo, esta solicitação usa o parâmetro de consulta `per_page` para retornar dois itens por página:\n\n```shell\ncurl --include --request GET \\\n--url \"https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2\" \\\n--header \"Accept: application/vnd.github+json\"\n```\n\nO parâmetro `per_page` será incluído automaticamente no cabeçalho de `link`. Por exemplo:\n\n```http\nlink: ; rel=\"next\", ; rel=\"last\"\n```\n\n## Script com paginação\n\nEm vez de copiar manualmente URLs do cabeçalho de `link`, você pode escrever um script para buscar várias páginas de resultados.\n\nOs exemplos a seguir usam JavaScript e a biblioteca Octokit.js do GitHub. Para obter mais informações sobre o Octokit.js, confira [Introdução à API REST](/pt/rest/using-the-rest-api/getting-started-with-the-rest-api?tool=javascript) e o arquivo [LEIAME do Octokit.js](https://github.com/octokit/octokit.js/#readme).\n\n### Exemplo de uso do método de paginação Octokit.js\n\nPara buscar resultados paginados com Octokit.js, você pode usar `octokit.paginate()`.\n`octokit.paginate()` buscará a próxima página de resultados até chegar à última página e retornará todos os resultados como uma única matriz. Alguns pontos de extremidade retornam resultados paginados como matriz em um objeto, em vez de retornar os resultados paginados como uma matriz.\n`octokit.paginate()` sempre retorna uma matriz de itens, mesmo que o resultado bruto tenha sido um objeto .\n\nPor exemplo, esse script obtém todos os problemas do repositório `octocat/Spoon-Knife`. Embora solicite 100 solicitações por vez, a função não retornará até que a última página de dados seja atingida.\n\n```javascript copy\nimport { Octokit } from \"octokit\";\n\nconst octokit = new Octokit({ );\n\nconst data = await octokit.paginate(\"GET /repos/{owner}/{repo}/issues\", {\n owner: \"octocat\",\n repo: \"Spoon-Knife\",\n per_page: 100,\n headers: {\n \"X-GitHub-Api-Version\": \"2026-03-10\",\n },\n});\n\nconsole.log(data)\n```\n\nVocê pode passar uma função de mapa opcional para `octokit.paginate()` para encerrar a paginação antes que a última página seja atingida ou para reduzir o uso de memória mantendo apenas um subconjunto da resposta. Você também pode usar `octokit.paginate.iterator()` para iterar uma única página por vez, em vez de solicitar todas as páginas. Para obter mais informações, confira [a documentação do Octokit.js](https://github.com/octokit/octokit.js#pagination).\n\n### Exemplo de criação de um método de paginação\n\nSe você estiver usando outro idioma ou biblioteca que não tenha um método de paginação, poderá criar seu próprio método de paginação. Este exemplo ainda usa a biblioteca de Octokit.js para fazer solicitações, mas não depende de `octokit.paginate()`.\n\nA função `getPaginatedData` faz uma solicitação para um endpoint com `octokit.request()`. Os dados da resposta são processados por `parseData`, que manipula casos em que nenhum dado é retornado ou casos em que os dados retornados são um objeto em vez de uma matriz. Os dados processados são acrescentados a uma lista que contém todos os dados paginados coletados até o momento. Se a resposta incluir um cabeçalho de `link` e se o cabeçalho de `link` incluir um link para a próxima página, a função usará um padrão RegEx (`nextPattern`) para obter a URL da próxima página. Em seguida, a função repete as etapas anteriores, agora usando essa nova URL. Quando o cabeçalho de `link` deixar de incluir um link para a próxima página, todos os resultados serão retornados.\n\n```javascript copy\nimport { Octokit } from \"octokit\";\n\nconst octokit = new Octokit({ );\n\nasync function getPaginatedData(url) {\n const nextPattern = /(?<=<)([\\S]*)(?=>; rel=\"next\")/i;\n let pagesRemaining = true;\n let data = [];\n\n while (pagesRemaining) {\n const response = await octokit.request(`GET ${url}`, {\n per_page: 100,\n headers: {\n \"X-GitHub-Api-Version\":\n \"2026-03-10\",\n },\n });\n\n const parsedData = parseData(response.data)\n data = [...data, ...parsedData];\n\n const linkHeader = response.headers.link;\n\n pagesRemaining = linkHeader && linkHeader.includes(`rel=\\\"next\\\"`);\n\n if (pagesRemaining) {\n url = linkHeader.match(nextPattern)[0];\n }\n }\n\n return data;\n}\n\nfunction parseData(data) {\n // If the data is an array, return that\n if (Array.isArray(data)) {\n return data\n }\n\n // Some endpoints respond with 204 No Content instead of empty array\n // when there is no data. In that case, return an empty array.\n if (!data) {\n return []\n }\n\n // Otherwise, the array of items that we want is in an object\n // Delete keys that don't include the array of items\n delete data.incomplete_results;\n delete data.repository_selection;\n delete data.total_count;\n // Pull out the array of items\n const namespaceKey = Object.keys(data)[0];\n data = data[namespaceKey];\n\n return data;\n}\n\nconst data = await getPaginatedData(\"/repos/octocat/Spoon-Knife/issues\");\n\nconsole.log(data);\n```"}