# Utilisation de la pagination dans l’API REST

Découvrez comment parcourir les réponses paginées de l’API REST.

## À propos de la pagination

Lorsqu’une réponse de l’API REST contient un grand nombre de résultats, GitHub paginera les résultats et renverra un sous-ensemble de ceux-ci. Par exemple, `GET /repos/octocat/Spoon-Knife/issues` ne retourne que 30 problèmes du dépôt `octocat/Spoon-Knife`, même si celui-ci compte plus de 1 600 problèmes ouverts. La réponse est ainsi plus facile à gérer pour les serveurs et pour les utilisateurs.

Vous pouvez utiliser l’en-tête `link` de la réponse pour demander des pages supplémentaires de données. Si un point de terminaison prend en charge le paramètre de requête `per_page`, vous pouvez contrôler le nombre de résultats retournés sur une page.

Cet article montre comment demander des pages de résultats supplémentaires pour les réponses paginées, comment changer le nombre de résultats retournés sur chaque page et comment écrire un script pour récupérer plusieurs pages de résultats.

## Utilisation d’en-têtes `link`

Quand une réponse est paginée, les en-têtes de réponse incluent un en-tête `link`. Si le point de terminaison ne prend pas en charge la pagination ou si tous les résultats rentrent sur une seule page, l'en-tête `link` sera omis.

L’en-tête `link` contient des URL que vous pouvez utiliser pour récupérer des pages supplémentaires de résultats. Par exemple, la page précédente, la suivante, la première et la dernière page des résultats.

Pour afficher les en-têtes de réponse d'un point de terminaison particulier, vous pouvez utiliser curl, GitHub CLI ou une bibliothèque que vous utilisez pour effectuer des requêtes. Pour voir les en-têtes de réponse si vous utilisez une bibliothèque pour effectuer des demandes, suivez la documentation de la bibliothèque en question. Pour afficher les en-têtes de réponse si vous utilisez curl ou GitHub CLI, passez l’indicateur `--include` avec votre requête. Par exemple :

```shell
curl --include --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json"
```

Si la réponse est paginée, l’en-tête `link` ressemble à ceci :

```http
link: <https://api.github.com/repositories/1300192/issues?page=2>; rel="prev", <https://api.github.com/repositories/1300192/issues?page=4>; rel="next", <https://api.github.com/repositories/1300192/issues?page=515>; rel="last", <https://api.github.com/repositories/1300192/issues?page=1>; rel="first"
```

L’en-tête `link` de lien fournit l’URL de la page précédente, de la page suivante, de la première page et de la dernière page des résultats :

* L’URL de la page précédente est suivie de `rel="prev"`.
* L’URL de la page suivante est suivie de `rel="next"`.
* L’URL de la dernière page est suivie de `rel="last"`.
* L’URL de la première page est suivie de `rel="first"`.

Dans certains cas, seule une partie de ces liens est disponible. Par exemple, le lien vers la page précédente n’est pas inclus si vous êtes sur la première page de résultats, et le lien vers la dernière page ne le sera pas non plus s’il ne peut pas être calculé.

Vous pouvez utiliser les URL de l’en-tête `link` pour demander une autre page de résultats. Par exemple, pour demander la dernière page de résultats selon l’exemple précédent :

```shell
curl --include --request GET \
--url "https://api.github.com/repositories/1300192/issues?page=515" \
--header "Accept: application/vnd.github+json"
```

Les URL dans l’en-tête `link` utilisent des paramètres de requête pour indiquer la page de résultats à afficher. Les paramètres de requête dans les URL `link` peuvent différer d’un point de terminaison à l’autre. Toutefois, chaque point de terminaison paginé utilise les paramètres de requête `page`, `before`/`after` ou `since`. (Certains points de terminaison utilisent le paramètre `since` pour autre chose que la pagination.) Dans tous les cas, vous pouvez utiliser les URL dans l’en-tête `link` pour récupérer des pages de résultats supplémentaires. Pour plus d’informations sur les paramètres de requête, consultez [Prise en main de l’API REST](/fr/enterprise-server@3.22/rest/using-the-rest-api/getting-started-with-the-rest-api#query-parameters).

## Changement du nombre d’éléments par page

Si un point de terminaison prend en charge le paramètre de requête `per_page`, vous pouvez contrôler le nombre de résultats retournés sur une page. Pour plus d’informations sur les paramètres de requête, consultez [Prise en main de l’API REST](/fr/enterprise-server@3.22/rest/using-the-rest-api/getting-started-with-the-rest-api#query-parameters).

Pour la plupart des points de terminaison, la valeur maximale est `per_page``100`. Si vous spécifiez une valeur supérieure à la valeur maximale, GitHub ne retourne pas d’erreur. Au lieu de cela, la valeur est automatiquement réduite au maximum, et la réponse ne comprend pas plus que le nombre maximal de résultats par page. Étant donné que la demande réussit toujours, vous pouvez recevoir moins de résultats que prévu sans indication que la `per_page` valeur a été réduite. Pour confirmer les valeurs par défaut et maximale `per_page` d’un point de terminaison, consultez la documentation de référence de ce point de terminaison.

Par exemple, cette requête utilise le paramètre de requête `per_page` pour retourner deux éléments par page :

```shell
curl --include --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json"
```

Le paramètre `per_page` sera automatiquement inclus dans l’en-tête `link`. Par exemple :

```http
link: <https://api.github.com/repositories/1300192/issues?per_page=2&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=2&page=7715>; rel="last"
```

## Écriture de scripts avec pagination

Au lieu de copier manuellement les URL à partir de l'en-tête `link`, vous pouvez écrire un script pour récupérer plusieurs pages de résultats.

Les exemples suivants utilisent JavaScript et GitHubla bibliothèque Octokit.js. Pour plus d’informations sur Octokit.js, consultez [Prise en main de l’API REST](/fr/enterprise-server@3.22/rest/using-the-rest-api/getting-started-with-the-rest-api?tool=javascript) et [le fichier LISEZMOI d’Octokit.js](https://github.com/octokit/octokit.js/#readme).

### Exemple utilisant la méthode de pagination Octokit.js

Pour récupérer des résultats paginés avec Octokit.js, vous pouvez utiliser `octokit.paginate()`.
`octokit.paginate()` récupère la page de résultats suivante jusqu’à atteindre la dernière page, puis retourne tous les résultats sous la forme d’un tableau. Quelques points de terminaison retournent les résultats paginés sous forme de tableau dans un objet, au lieu de les retourner sous forme de tableau.
`octokit.paginate()` retourne toujours un tableau d’éléments même si le résultat brut était un objet.

Par exemple, ce script obtient tous les problèmes du dépôt `octocat/Spoon-Knife`. Bien qu'elle demande 100 requêtes à la fois, la fonction ne renverra rien tant que la dernière page de données n'aura pas été atteinte.

```javascript copy
import { Octokit } from "octokit";

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
);

const data = await octokit.paginate("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  per_page: 100,
  headers: {
    "X-GitHub-Api-Version": "2026-03-10",
  },
});

console.log(data)
```

Vous pouvez passer une fonction de mappage facultative à `octokit.paginate()` pour mettre fin à la pagination avant que la dernière page ne soit atteinte ou pour réduire l’utilisation de la mémoire en conservant uniquement une partie de la réponse. Vous pouvez également utiliser `octokit.paginate.iterator()` pour itérer au sein d’une seule page à la fois au lieu de demander chaque page. Pour plus d’informations, consultez [la documentation d’Octokit.js](https://github.com/octokit/octokit.js#pagination).

### Exemple de création d’une méthode de pagination

Si vous utilisez un autre langage ou une autre bibliothèque qui n’a pas de méthode de pagination, vous pouvez créer votre propre méthode de pagination. Cet exemple utilise quand même la bibliothèque Octokit.js pour faire des demandes, mais ne s’appuie pas sur `octokit.paginate()`.

La fonction `getPaginatedData` effectue une requête vers un point de terminaison avec `octokit.request()`. Les données de la réponse sont traitées par `parseData`, qui gère les cas où aucune donnée n’est retournée ou les cas où les données retournées sont un objet au lieu d’un tableau. Les données traitées sont ensuite ajoutées à une liste qui contient toutes les données paginées collectées jusqu’ici. Si la réponse inclut un en-tête `link` de lien et si l’en-tête `link` de lien inclut un lien pour la page suivante, la fonction utilise un pattern RegEx (`nextPattern`) pour obtenir l’URL de la page suivante. La fonction répète ensuite les étapes précédentes, en utilisant désormais cette nouvelle URL. Une fois que l’en-tête `link` n’inclut plus de lien vers la page suivante, tous les résultats sont renvoyés.

```javascript copy
import { Octokit } from "octokit";

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
);

async function getPaginatedData(url) {
  const nextPattern = /(?<=<)([\S]*)(?=>; rel="next")/i;
  let pagesRemaining = true;
  let data = [];

  while (pagesRemaining) {
    const response = await octokit.request(`GET ${url}`, {
      per_page: 100,
      headers: {
        "X-GitHub-Api-Version":
          "2026-03-10",
      },
    });

    const parsedData = parseData(response.data)
    data = [...data, ...parsedData];

    const linkHeader = response.headers.link;

    pagesRemaining = linkHeader && linkHeader.includes(`rel=\"next\"`);

    if (pagesRemaining) {
      url = linkHeader.match(nextPattern)[0];
    }
  }

  return data;
}

function parseData(data) {
  // If the data is an array, return that
    if (Array.isArray(data)) {
      return data
    }

  // Some endpoints respond with 204 No Content instead of empty array
  //   when there is no data. In that case, return an empty array.
  if (!data) {
    return []
  }

  // Otherwise, the array of items that we want is in an object
  // Delete keys that don't include the array of items
  delete data.incomplete_results;
  delete data.repository_selection;
  delete data.total_count;
  // Pull out the array of items
  const namespaceKey = Object.keys(data)[0];
  data = data[namespaceKey];

  return data;
}

const data = await getPaginatedData("/repos/octocat/Spoon-Knife/issues");

console.log(data);
```