Prise en main de l’API REST

Pour effectuer une requête à l’aide de JavaScript, vous pouvez utiliser Octokit.js. Pour plus d’informations, consultez « Écriture de scripts avec l’API REST et JavaScript ».

Tout d’abord, créez une instance de Octokit. Définissez l’URL de base sur http(s)://HOSTNAME/api/v3. Remplacez [hostname] par le nom de votre instance GitHub Enterprise Server.

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

Ensuite, utilisez la méthode request pour effectuer des requêtes. Passez la méthode HTTP et le chemin en tant que premier argument.

await octokit.request("GET /octocat", {});

Pour vous authentifier auprès de la bibliothèque Octokit.js, vous pouvez passer votre jeton quand vous créez une instance de Octokit. Remplacez YOUR-TOKEN par votre jeton. Remplacez [hostname] par le nom de votre instance GitHub Enterprise Server.

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: 'YOUR-TOKEN',
});

Vous pouvez aussi utiliser le mot clé run pour exécuter vos scripts JavaScript dans vos workflows GitHub Actions. Pour plus d’informations, consultez « Workflow syntax for GitHub Actions ».

GitHub vous recommande de vous authentifier avec le jeton GITHUB_TOKEN intégré 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 « Authentification par jeton automatique ». Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ».

L’exemple de workflow suivant effectue ceci :

1. Il extrait 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.

Exemple de workflow :

on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - name: Check out repo content
        uses: actions/checkout@v3

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

      - name: Install dependencies
        run: npm install octokit

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

Exemple de script JavaScript, avec le chemin de fichier .github/actions-scripts/use-the-api.mjs :

import { Octokit } from "octokit";

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: process.env.TOKEN,
});

await octokit.request("GET /octocat", {});

Au lieu de stocker votre script dans un fichier distinct et de l’exécuter à partir de votre workflow, vous pouvez utiliser l’action actions/github-script pour exécuter un script. Pour plus d’informations, consultez le fichier Lisez-moi actions/github-script.

jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - uses: actions/github-script@v6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            await github.request('GET /octocat', {})

La bibliothèque Octokit.js passe automatiquement l’en-tête Accept: application/vnd.github+json. Pour passer des en-têtes supplémentaires ou un en-tête Accept différent, ajoutez une propriété headers à l’objet passé en tant que deuxième argument à la méthode request. La valeur de la propriété headers est un objet avec les noms d’en-tête en tant que clés et les valeurs d’en-tête en tant que valeurs. Par exemple, pour envoyer un en-tête content-type avec la valeur de text/plain :

await octokit.request("GET /octocat", {
  headers: {
    "content-type": "text/plain",
  },
});

Quand vous effectuez une requête avec Octokit.js, tous les paramètres, y compris les paramètres de chemin, sont passés dans un objet en tant que deuxième argument à la méthode request. Pour obtenir les problèmes provenant du dépôt octocat/Spoon-Knife, spécifiez owner en tant que octocat et repo en tant que Spoon-Knife.

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

Quand vous effectuez une requête avec Octokit.js, tous les paramètres, y compris les paramètres de requête, sont passés dans un objet en tant que deuxième argument à la méthode request.

await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  per_page: 2,
  sort: "updated",
  direction: "asc",
});

Quand vous effectuez une requête avec Octokit.js, tous les paramètres, y compris les paramètres de corps, sont passés dans un objet en tant que deuxième argument à la méthode request.

await octokit.request("POST /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  title: "Created with the REST API",
  body: "This is a test issue created by the REST API",
});

Quand vous effectuez une requête avec Octokit.js, la méthode request retourne une promesse. Si la requête réussit, la promesse est résolue en objet qui inclut le code d’état HTTP de la réponse (status) et les en-têtes de réponse (headers). Si une erreur se produit, la promesse est résolue en objet qui inclut le code d’état HTTP de la réponse (status) et les en-têtes de réponse (response.headers).

Vous pouvez utiliser un bloc try/catch pour intercepter une erreur éventuelle. Par exemple, si la requête indiquée dans le script suivant réussit, le script journalise le code d’état et la valeur de l’en-tête x-ratelimit-remaining. Si la requête échoue, le script journalise le code d’état, la valeur de l’en-tête x-ratelimit-remaining et le message d’erreur.

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

  console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers["x-ratelimit-remaining"]}`)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers["x-ratelimit-remaining"]}. Message: ${error.response.data.message}`)
}

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

Par exemple, vous pouvez obtenir le titre et l’ID d’auteur de chaque problème :

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

  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}`)
}