# Démarrage rapide pour l’API REST GitHub

Découvrez comment bien démarrer avec l’API REST GitHub.

## Introduction

Cet article explique comment rapidement bien démarrer avec l’API REST GitHub à l’aide de GitHub CLI,`curl` ou JavaScript. Pour obtenir un guide plus détaillé, consultez [Prise en main de l’API REST](/fr/rest/guides/getting-started-with-the-rest-api).

<div class="ghd-tool cli">

## Utilisation de GitHub CLI dans la ligne de commande

GitHub CLI constitue la manière la plus facile d’utiliser l’API REST GitHub à partir de la ligne de commande.

1. Installez GitHub CLI sur macOS, Windows ou Linux. Pour en savoir plus, consultez [Installation](https://github.com/cli/cli?ref_product=cli\&ref_type=engagement\&ref_style=text#installation) dans le référentiel GitHub CLI.

2. Pour vous authentifier sur GitHub, exécutez la commande suivante depuis votre terminal.

   ```shell
   gh auth login
   ```

3. Sélectionnez l'endroit où vous souhaitez vous authentifier :

   * Si vous accédez à GitHub à GitHub.com, sélectionnez **GitHub.com**.
   * Si vous accédez à GitHub sur un autre domaine, sélectionnez **Autre** , puis entrez votre nom d'hôte (par exemple : `octocorp.ghe.com`).

4. Suivez les autres invites à l'écran.

   GitHub CLI enregistre automatiquement vos identifiants Git lorsque vous choisissez HTTPS comme protocole préféré pour les opérations Git et que vous répondez « oui » à l'invite vous demandant si vous souhaitez vous authentifier sur Git avec vos identifiants GitHub. Ce procédé peut être utile car il vous permet d'utiliser les commandes Git telles que `git push` et `git pull`, sans avoir à configurer un gestionnaire d'informations d'identification distinct ou à utiliser SSH.

5. Exécutez une requête à l’aide de la sous-commande GitHub CLI `api`, suivie du chemin d’accès. Utilisez l’indicateur `--method` ou `-X` pour spécifier la méthode. Pour plus d'informations, consultez la [documentation de GitHub CLI `api`](https://cli.github.com/manual/gh_api).

   Cet exemple interroge le point de terminaison « Get Octocat », qui utilise la méthode `GET` et le chemin d’accès `/octocat`. Pour obtenir la documentation de référence complète de ce point de terminaison, consultez [Points de terminaison d’API REST pour les métadonnées](/fr/rest/meta/meta#get-octocat).

   ```shell copy
   gh api /octocat --method GET
   ```

## Utilisation de GitHub CLI dans GitHub Actions

Vous pouvez aussi utiliser GitHub CLI dans vos workflows GitHub Actions. Pour plus d’informations, consultez « [Utilisation de l’interface CLI GitHub dans les flux de travail](/fr/actions/using-workflows/using-github-cli-in-workflows) ».

### S’authentifier avec un jeton d’accès

Au lieu d’utiliser la commande `gh auth login`, passez un jeton d’accès en tant que variable d’environnement appelée `GH_TOKEN`. GitHub vous recommande d’utiliser l’utilitaire intégré `GITHUB_TOKEN` au lieu de créer un jeton. Si ce n’est pas possible, stockez votre jeton sous forme de secret et remplacez `GITHUB_TOKEN` dans l’exemple ci-dessous par le nom de votre secret. Pour plus d’informations sur `GITHUB_TOKEN`, consultez [Utiliser GITHUB\_TOKEN pour l’authentification dans les flux de travail](/fr/actions/security-guides/automatic-token-authentication). Pour plus d’informations sur les secrets, consultez « [Utilisation de secrets dans GitHub Actions](/fr/actions/security-guides/encrypted-secrets) ».

L’exemple de flux de travail suivant utilise le point de terminaison [Répertorier les problèmes du référentiel](/fr/rest/issues/issues#list-repository-issues) et demande une liste de problèmes dans le référentiel `octocat/Spoon-Knife`.

```yaml copy
on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api https://api.github.com/repos/octocat/Spoon-Knife/issues
```

### Authentification avec l'GitHub App

Si vous vous authentifiez avec une GitHub App, vous pouvez créer un jeton d’accès d’installation au sein de votre workflow :

1. Stockez l’ID de votre GitHub App sous forme de variable de configuration. Dans l’exemple suivant, remplacez `APP_ID` par le nom de la variable de configuration. Vous pouvez trouver votre ID d’application dans la page Paramètres de votre application ou via l’API. Pour plus d’informations, consultez « [Points de terminaison d’API REST pour GitHub Apps](/fr/rest/apps/apps#get-an-app) ». Pour plus d’informations concernant les variables de configuration, consultez [Stocker des informations dans des variables](/fr/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows).
2. Générez une clé privée pour votre application. Stockez le contenu du fichier obtenu dans un secret. (Stockez l’intégralité du contenu du fichier, y compris `-----BEGIN RSA PRIVATE KEY-----` et `-----END RSA PRIVATE KEY-----`.) Dans l’exemple suivant, remplacez `APP_PEM` par le nom du secret. Pour plus d’informations, consultez « [Gestion des clés privées pour les applications GitHub](/fr/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps) ». Pour plus d’informations sur les secrets, consultez « [Utilisation de secrets dans GitHub Actions](/fr/actions/security-guides/encrypted-secrets) ».
3. Ajoutez une étape pour générer un jeton, puis utilisez ce jeton au lieu de `GITHUB_TOKEN`. Notez que ce jeton expire au bout de 60 minutes. Par exemple :

   ```yaml copy
   on:
     workflow_dispatch:
   jobs:
     track_pr:
       runs-on: ubuntu-latest
       steps:
         - name: Generate token
           id: generate-token
           uses: actions/create-github-app-token@v2
           with:
             app-id: ${{ vars.APP_ID }}
             private-key: ${{ secrets.APP_PEM }}
         - name: Use API
           env:
             GH_TOKEN: ${{ steps.generate-token.outputs.token }}
           run: |
             gh api https://api.github.com/repos/octocat/Spoon-Knife/issues
   ```

</div>

<div class="ghd-tool javascript">

## Utilisation d’Octokit.js

Vous pouvez utiliser Octokit.js pour interagir avec l’API REST GitHub dans vos scripts JavaScript. Pour plus d’informations, consultez [Écriture de scripts avec l’API REST et JavaScript](/fr/rest/guides/scripting-with-the-rest-api-and-javascript).

1. Créez un jeton d’accès. Par exemple, créez un personal access token ou un jeton d’accès utilisateur GitHub App. Vous utiliserez ce jeton pour authentifier votre demande. Vous devez donc lui accorder toutes les étendues ou autorisations requises pour accéder à ce point de terminaison. Pour plus d’informations, consultez [Authentification auprès de l’API REST](/fr/rest/overview/authenticating-to-the-rest-api) ou [Identifier et autoriser les utilisateurs pour GitHub Apps](/fr/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps).

   > \[!WARNING]
   > Considérez le jeton d’accès comme un mot de passe.
   >
   > Pour sécuriser votre jeton, vous pouvez stocker votre jeton sous forme de secret et exécuter votre script par le biais de GitHub Actions. Pour plus d’informations, consultez la section [Utilisation d’Octokit.js dans GitHub Actions](#using-octokitjs-in-github-actions).

   Vous pouvez aussi stocker votre jeton sous forme de secret Codespaces et exécuter votre script dans Codespaces. Pour plus d’informations, consultez [Gestion des secrets chiffrés pour vos espaces de code](/fr/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces).

   > Si ces options ne sont pas possibles, envisagez d’utiliser un autre service CLI pour stocker votre jeton en toute sécurité.

2. Installez `octokit`. Par exemple : `npm install octokit`. Pour découvrir d’autres manières d’installer ou charger `octokit`, consultez [le README d’Octokit.js](https://github.com/octokit/octokit.js/#readme).

3. Importez `octokit` dans votre script. Par exemple : `import { Octokit } from "octokit";`. Pour d'autres moyens d'importer `octokit`, consultez le README d'Octokit.js.

4. créer une instance de `Octokit` à l’aide de votre jeton. Remplacez `YOUR-TOKEN` par votre jeton.

   ```javascript copy
   const octokit = new Octokit({ 
     auth: 'YOUR-TOKEN'
   });
   ```

5. Utilisez `octokit.request` pour exécuter votre requête. Envoyez la méthode HTTP et le chemin en tant que premier argument. Spécifiez tous les paramètres de chemin, de requête et de corps dans un objet en tant que deuxième argument. Pour plus d’informations sur les paramètres, consultez [Prise en main de l’API REST](/fr/rest/guides/getting-started-with-the-rest-api#using-parameters).

   Par exemple, dans la demande suivante, la méthode HTTP est `GET`, le chemin d’accès est `/repos/{owner}/{repo}/issues`, et les paramètres sont `owner: "octocat"` et `repo: "Spoon-Knife"`.

   ```javascript copy
   await octokit.request("GET /repos/{owner}/{repo}/issues", {
     owner: "octocat",
     repo: "Spoon-Knife",
   });
   ```

## Utilisation d’Octokit.js dans GitHub Actions

Vous pouvez aussi exécuter vos scripts JavaScript dans vos workflows GitHub Actions. Pour plus d’informations, consultez « [Syntaxe de flux de travail pour GitHub Actions](/fr/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun) ».

### S’authentifier avec un jeton d’accès

GitHub vous recommande d’utiliser l’utilitaire intégré `GITHUB_TOKEN` au lieu de créer un jeton. Si ce n’est pas possible, stockez votre jeton sous forme de secret et remplacez `GITHUB_TOKEN` dans l’exemple ci-dessous par le nom de votre secret. Pour plus d’informations sur `GITHUB_TOKEN`, consultez [Utiliser GITHUB\_TOKEN pour l’authentification dans les flux de travail](/fr/actions/security-guides/automatic-token-authentication). Pour plus d’informations sur les secrets, consultez « [Utilisation de secrets dans GitHub Actions](/fr/actions/security-guides/encrypted-secrets) ».

L'exemple de flux de travail suivant :

1. Consulte le contenu du dépôt.
2. Il configure Node.js.
3. Il installe `octokit`.
4. Il stocke la valeur de `GITHUB_TOKEN` sous forme de variable d’environnement appelée `TOKEN` et exécute `.github/actions-scripts/use-the-api.mjs`, qui peut accéder à cette variable d’environnement en tant que `process.env.TOKEN`.

```yaml
on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - name: Check out repo content
        uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '16.17.0'
          cache: npm

      - name: Install dependencies
        run: npm install octokit

      - name: Run script
        run: |
          node .github/actions-scripts/use-the-api.mjs
        env:
          TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

Voici un exemple de script JavaScript avec le chemin d’accès de fichier `.github/actions-scripts/use-the-api.mjs`.

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

const octokit = new Octokit({ 
  auth: process.env.TOKEN
});

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
      owner: "octocat",
      repo: "Spoon-Knife",
    });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}
```

### Authentification avec l'GitHub App

Si vous vous authentifiez avec une GitHub App, vous pouvez créer un jeton d’accès d’installation au sein de votre workflow :

1. Stockez l’ID de votre GitHub App sous forme de variable de configuration. Dans l’exemple suivant, remplacez `APP_ID` par le nom de la variable de configuration. Vous pouvez trouver votre ID d’application dans la page Paramètres de votre application ou via l’API d’application. Pour plus d’informations, consultez « [Points de terminaison d’API REST pour GitHub Apps](/fr/rest/apps/apps#get-an-app) ». Pour plus d’informations concernant les variables de configuration, consultez [Stocker des informations dans des variables](/fr/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows).
2. Générez une clé privée pour votre application. Stockez le contenu du fichier obtenu dans un secret. (Stockez l’intégralité du contenu du fichier, y compris `-----BEGIN RSA PRIVATE KEY-----` et `-----END RSA PRIVATE KEY-----`.) Dans l’exemple suivant, remplacez `APP_PEM` par le nom du secret. Pour plus d’informations, consultez « [Gestion des clés privées pour les applications GitHub](/fr/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps) ». Pour plus d’informations sur les secrets, consultez « [Utilisation de secrets dans GitHub Actions](/fr/actions/security-guides/encrypted-secrets) ».
3. Ajoutez une étape pour générer un jeton, puis utilisez ce jeton au lieu de `GITHUB_TOKEN`. Notez que ce jeton expire au bout de 60 minutes. Par exemple :

   ```yaml
   on:
     workflow_dispatch:
   jobs:
     use_api_via_script:
       runs-on: ubuntu-latest
       steps:
         - name: Check out repo content
           uses: actions/checkout@v6

         - name: Setup Node
           uses: actions/setup-node@v4
           with:
             node-version: '16.17.0'
             cache: npm

         - name: Install dependencies
           run: npm install octokit

         - name: Generate token
           id: generate-token
           uses: actions/create-github-app-token@v2
           with:
             app-id: ${{ vars.APP_ID }}
             private-key: ${{ secrets.APP_PEM }}

         - name: Run script
           run: |
             node .github/actions-scripts/use-the-api.mjs
           env:
             TOKEN: ${{ steps.generate-token.outputs.token }}

   ```

</div>

<div class="ghd-tool curl">

## Utilisation de `curl` dans la ligne de commande

> \[!NOTE]
> Si vous voulez créer des requêtes d’API à partir de la ligne de commande, GitHub vous recommande d’utiliser GitHub CLI, ce qui simplifie l’authentification et les requêtes. Pour plus d’informations sur la prise en main de l’API REST à l’aide de GitHub CLI, consultez la version GitHub CLI de cet article.

1. Installez `curl` s’il n’est pas déjà installé sur votre ordinateur. Pour vérifier si `curl` est installé, exécutez `curl --version` dans la ligne de commande. Si la sortie fournit des informations sur la version de `curl`, cela signifie que `curl` est installé. Si vous recevez un message comme `command not found: curl`, vous avez besoin de télécharger et d’installer `curl`. Pour plus d’informations, consultez [la page de téléchargement du projet curl](https://curl.se/download.html).

2. Créez un jeton d’accès. Par exemple, créez un personal access token ou un jeton d’accès utilisateur GitHub App. Vous utiliserez ce jeton pour authentifier votre demande. Vous devez donc lui accorder toutes les étendues ou autorisations requises pour accéder au point de terminaison. Pour plus d’informations, consultez « [Authentification auprès de l’API REST](/fr/rest/overview/authenticating-to-the-rest-api) ».

   > \[!WARNING]
   > Considérez le jeton d’accès comme un mot de passe.
   >
   > Pour sécuriser votre jeton, vous pouvez aussi le stocker sous forme de secret Codespaces et utiliser la ligne de commande dans Codespaces. Pour plus d’informations, consultez [Gestion des secrets chiffrés pour vos espaces de code](/fr/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces).

   > Vous pouvez aussi utiliser GitHub CLI au lieu de `curl`. GitHub CLI s’occupe de l’authentification pour vous. Pour plus d’informations, consultez la version GitHub CLI de cette page.
   >
   > Si ces options ne sont pas possibles, envisagez d’utiliser un autre service CLI pour stocker votre jeton en toute sécurité.

3. Utilisez la commande `curl` pour effectuer votre requête. Passez votre jeton dans un en-tête `Authorization`. Remplacez `YOUR-TOKEN` par votre jeton.

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

   > \[!NOTE]
   > Dans la plupart des cas, vous pouvez utiliser `Authorization: Bearer` ou `Authorization: token` pour passer un jeton. Toutefois, si vous passez un jeton web JSON (JWT), vous devez utiliser `Authorization: Bearer`.

## Utilisation de commandes `curl` dans GitHub Actions

Vous pouvez aussi utiliser des commandes `curl` dans vos workflows GitHub Actions.

### S’authentifier avec un jeton d’accès

GitHub vous recommande d’utiliser l’utilitaire intégré `GITHUB_TOKEN` au lieu de créer un jeton. Si ce n’est pas possible, stockez votre jeton sous forme de secret et remplacez `GITHUB_TOKEN` dans l’exemple ci-dessous par le nom de votre secret. Pour plus d’informations sur `GITHUB_TOKEN`, consultez [Utiliser GITHUB\_TOKEN pour l’authentification dans les flux de travail](/fr/actions/security-guides/automatic-token-authentication). Pour plus d’informations sur les secrets, consultez « [Utilisation de secrets dans GitHub Actions](/fr/actions/security-guides/encrypted-secrets) ».

```yaml copy
on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"
```

### Authentification avec l'GitHub App

Si vous vous authentifiez avec une GitHub App, vous pouvez créer un jeton d’accès d’installation au sein de votre workflow :

1. Stockez l’ID de votre GitHub App sous forme de variable de configuration. Dans l’exemple suivant, remplacez `APP_ID` par le nom de la variable de configuration. Vous pouvez trouver votre ID d’application dans la page Paramètres de votre application ou via l’API d’application. Pour plus d’informations, consultez « [Points de terminaison d’API REST pour GitHub Apps](/fr/rest/apps/apps#get-an-app) ». Pour plus d’informations concernant les variables de configuration, consultez [Stocker des informations dans des variables](/fr/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows).
2. Générez une clé privée pour votre application. Stockez le contenu du fichier obtenu dans un secret. (Stockez l’intégralité du contenu du fichier, y compris `-----BEGIN RSA PRIVATE KEY-----` et `-----END RSA PRIVATE KEY-----`.) Dans l’exemple suivant, remplacez `APP_PEM` par le nom du secret. Pour plus d’informations, consultez « [Gestion des clés privées pour les applications GitHub](/fr/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps) ». Pour plus d’informations sur le stockage de secrets, consultez « [Utilisation de secrets dans GitHub Actions](/fr/actions/security-guides/encrypted-secrets) ».
3. Ajoutez une étape pour générer un jeton, puis utilisez ce jeton au lieu de `GITHUB_TOKEN`. Notez que ce jeton expire au bout de 60 minutes. Par exemple :

   ```yaml copy
   on:
     workflow_dispatch:
   jobs:
     use_api:
       runs-on: ubuntu-latest
       steps:
         - name: Generate token
           id: generate-token
           uses: actions/create-github-app-token@v2
           with:
             app-id: ${{ vars.APP_ID }}
             private-key: ${{ secrets.APP_PEM }}

         - name: Use API
           env:
             GH_TOKEN: ${{ steps.generate-token.outputs.token }}
           run: |
             curl --request GET \
             --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
             --header "Accept: application/vnd.github+json" \
             --header "Authorization: Bearer $GH_TOKEN"

   ```

</div>

## Étapes suivantes

Pour obtenir un guide plus détaillé, consultez [Bien démarrer avec l’API REST](/fr/rest/guides/getting-started-with-the-rest-api).