Skip to main content
Nous publions des mises à jour fréquentes de notre documentation, et la traduction de cette page peut encore être en cours. Pour obtenir les informations les plus actuelles, consultez la documentation anglaise.

Prise en main de l’API REST

Découvrez comment utiliser l’API REST GitHub.

À propos de l’API REST GitHub

Cet article explique comment utiliser l’API REST GitHub à l’aide de GitHub CLI, JavaScript ou curl. Pour obtenir un guide de démarrage rapide, consultez « Démarrage rapide pour l’API REST GitHub ».

Quand vous effectuez une requête avec l’API REST, vous spécifiez une méthode HTTP et un chemin. De plus, vous pouvez éventuellement spécifier des en-têtes de demande et des paramètres de chemin, de requête ou de corps. L’API retourne le code d’état de la réponse, les en-têtes de réponse et éventuellement un corps de réponse.

La documentation de référence de l’API REST décrit la méthode HTTP, le chemin et les paramètres de chaque opération. Elle présente aussi des exemples de requêtes et de réponses pour chaque opération. Pour plus d’informations, consultez la documentation de référence sur REST.

Pour plus d’informations sur les API de GitHub, consultez « À propos des API de GitHub ».

Création d’une requête

Pour effectuer une requête, recherchez d’abord la méthode HTTP et le chemin de l’opération que vous voulez utiliser. Par exemple, l’opération « Get Octocat » utilise la méthode GET et le chemin /octocat. Pour obtenir la documentation de référence complète de cette opération, consultez « Get Octocat ».

Remarque : Vous devez installer GitHub CLI pour utiliser les commandes mentionnées dans les exemples GitHub CLI. Pour obtenir des instructions d’installation, consultez le dépôt GitHub CLI.

Si vous n’êtes pas déjà authentifié auprès de GitHub CLI, vous devez utiliser la sous-commande gh auth login pour vous authentifier avant d’effectuer toute requête. Pour plus d’informations, consultez « Authentification ».

Pour effectuer une requête à l’aide de GitHub CLI, utilisez la sous-commande api avec le chemin. Utilisez l’indicateur --method ou -X pour spécifier la méthode.

gh api /octocat --method GET

Remarque : Vous devez installer et importer octokit pour utiliser la bibliothèque Octokit.js utilisée dans les exemples JavaScript. Pour plus d’informations, consultez le fichier Lisez-moi d’Octokit.js.

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.

const octokit = new Octokit({ });

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", {});

Ajoutez l’URL de base de l’API REST GitHub, https://api.github.com, au début du chemin pour obtenir l’URL complète : https://api.github.com/octocat.

Utilisez la commande curl dans votre ligne de commande. Utilisez l’indicateur --request ou -X suivi de la méthode HTTP. Utilisez l’indicateur --url suivi de l’URL complète.

curl --request GET \
--url "https://api.github.com/octocat"

Remarque : Si vous obtenez un message similaire à « Commande introuvable : curl », vous devrez peut-être télécharger et installer curl. Pour plus d’informations, consultez la page de téléchargement du projet .

Poursuivez votre lecture pour savoir comment vous authentifier, envoyer des paramètres et utiliser la réponse.

Authentification

De nombreuses opérations nécessitent une authentification ou retournent des informations supplémentaires si vous êtes authentifié. De plus, vous pouvez effectuer davantage de requêtes par heure quand vous êtes authentifié.

Bien que certaines opérations d’API REST soient accessibles sans authentification, vous devez vous authentifier auprès de GitHub CLI pour utiliser la sous-commande api.

À propos des jetons

Vous pouvez authentifier votre requête en ajoutant un jeton.

Si vous voulez utiliser l’API REST GitHub à des fins personnelles, vous pouvez créer un personal access token. Les opérations de l’API REST utilisées dans cet article nécessitent l’étendue repo pour les personal access tokens (classic) ou, sauf indication contraire, un accès en lecture seule aux dépôts publics pour les fine-grained personal access token. Les autres opérations peuvent nécessiter d’autres étendues ou autorisations. Pour plus d’informations sur la création d’un personal access token, consultez « Création d’un personal access token ».

Si vous voulez utiliser l’API au nom d’une organisation ou d’un autre utilisateur, GitHub vous recommande d’utiliser une GitHub App. Si une opération est disponible pour GitHub Apps, la documentation de référence sur REST pour cette opération indique « Fonctionne avec GitHub Apps ». Les opérations d’API REST utilisées dans cet article nécessitent des autorisations d’accès en lecture et écriture issues pour GitHub Apps. D’autres opérations peuvent nécessiter des autorisations différentes. Pour plus d’informations, consultez « Création d’une application GitHub », « Authentification avec les applications GitHub et « Identification et autorisation des utilisateurs pour les applications GitHub ».

Si vous voulez utiliser l’API dans un workflow GitHub Actions, GitHub vous recommande d’être authentifié avec le jeton GITHUB_TOKEN intégré au lieu de créer un jeton. Vous pouvez accorder des autorisations au GITHUB_TOKEN avec la clé permissions. Pour plus d’informations, consultez « Authentification automatique par jeton ».

Exemple d’authentification

Avec GitHub CLI, vous n’avez pas besoin de créer un jeton d’accès à l’avance. Utilisez la sous-commande auth login pour vous authentifier auprès de GitHub CLI :

gh auth login

Vous pouvez utiliser l’indicateur --scopes pour spécifier les étendues voulues. Si vous voulez vous authentifier avec un jeton que vous avez créé, vous pouvez utiliser l’indicateur --with-token. Pour plus d’informations, consultez la documentation sur la sous-commande GitHub CLI auth login.

Avertissement : Considérez votre 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 « Secrets chiffrés ».

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 codespaces ».

Si ces options ne sont pas possibles, envisagez d’utiliser un autre service comme l’interface CLI 1Password pour stocker votre jeton de manière sécurisée.

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.

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

Avertissement : Considérez votre jeton d’accès comme un mot de passe.

Pour sécuriser votre compte, vous pouvez utiliser GitHub CLI au lieu de commandes curl. GitHub CLI s’occupe de l’authentification pour vous. Pour plus d’informations, consultez la version GitHub CLI de cette page.

Vous pouvez aussi stocker votre jeton 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 codespaces ».

Si ces options ne sont pas possibles, envisagez d’utiliser un autre service comme l’interface CLI 1Password pour stocker votre jeton de manière sécurisée.

Dans des commandes curl, vous allez envoyer un en-tête Authorization avec votre jeton. Remplacez YOUR-TOKEN par votre jeton :

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Authorization: Bearer YOUR-TOKEN"

Remarque : 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.

Exemple d’authentification pour GitHub Actions

Vous pouvez aussi utiliser le mot clé run pour exécuter des commandes GitHub CLI dans vos workflows GitHub Actions. Pour plus d’informations, consultez « Syntaxe de workflow pour GitHub Actions ».

Au lieu d’utiliser la commande gh auth login, passez votre jeton en tant que variable d’environnement appelée GH_TOKEN. 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 automatique par jeton ». Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ».

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api /octocat

Vous pouvez aussi utiliser le mot clé run pour exécuter vos scripts JavaScript dans vos workflows GitHub Actions. Pour plus d’informations, consultez « Syntaxe de workflow pour 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 automatique par jeton ». 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({ 
  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', {})

Vous pouvez aussi utiliser le mot clé run pour exécuter des commandes curl dans vos workflows GitHub Actions. Pour plus d’informations, consultez « Syntaxe de workflow pour 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 automatique par jeton ». Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ».

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/octocat" \
          --header "Authorization: Bearer $GH_TOKEN"

Utilisation d’en-têtes

La plupart des opérations spécifient que vous devez passer un en-tête Accept avec une valeur de application/vnd.github+json. D’autres opérations peuvent spécifier que vous devez envoyer un en-tête Accept différent ou des en-têtes supplémentaires.

Pour envoyer un en-tête avec GitHub CLI, utilisez l’indicateur --header ou -H suivi de l’en-tête au format key: value.

gh api --header 'Accept: application/vnd.github+json' --header 'X-GitHub-Api-Version:2022-11-28' --method 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",
    "X-GitHub-Api-Version": "2022-11-28",
  },
});

Pour envoyer un en-tête dans une commande curl, utilisez l’indicateur --header ou -H suivi de l’en-tête au format key: value.

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"\
--header "X-GitHub-Api-Version: 2022-11-28"

Utilisation de paramètres de chemin

Les paramètres de chemin modifient le chemin de l’opération. Par exemple, le chemin « Lister les problèmes d’un dépôt » est /repos/{owner}/{repo}/issues. Les accolades {} reflètent des paramètres de chemin que vous avez besoin de spécifier. Dans cet exemple, vous devez spécifier le propriétaire et le nom du dépôt. Pour accéder à la documentation de référence de cette opération, consultez « Lister les problèmes d’un dépôt ».

Pour obtenir les problèmes provenant du dépôt octocat/Spoon-Knife, remplacez {owner} par octocat et {repo} par Spoon-Knife.

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues

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"
});

Pour obtenir les problèmes provenant du dépôt octocat/Spoon-Knife, remplacez {owner} par octocat et {repo} par Spoon-Knife. Pour générer le chemin complet, ajoutez l’URL de base de l’API REST GitHub, https://api.github.com, au début : https://api.github.com/repos/octocat/Spoon-Knife/issues.

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

L’opération retourne la liste des problèmes et des données sur chaque problème. Pour plus d’informations sur l’utilisation de la réponse, consultez la section « Utilisation de la réponse ».

Utilisation de paramètres de requête

Les paramètres de requête vous permettent de contrôler les données retournées pour une requête. Par exemple, un paramètre de requête peut vous permettre de spécifier le nombre d’éléments retournés quand la réponse est paginée.

Par défaut, l’opération « Lister les problèmes d’un dépôt » retourne trente problèmes, triés dans l’ordre décroissant par leur date de création. Vous pouvez utiliser le paramètre per_page pour renvoyer deux problèmes au lieu de 30. Vous pouvez utiliser le paramètre sort pour trier les problèmes par leur date de dernière mise à jour plutôt que leur date de création. Vous pouvez utiliser le paramètre direction pour trier les résultats dans l’ordre croissant plutôt que dans l’ordre décroissant.

Pour GitHub CLI, utilisez l’indicateur -F pour passer un paramètre qui correspond à un nombre, une valeur booléenne ou Null. Utilisez -f pour passer des paramètres de chaîne.

Remarque : Actuellement, GitHub CLI n’accepte pas les paramètres qui correspondent à des tableaux. Pour plus d’informations, consultez ce problème.

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 -f sort=updated -f direction=asc

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",
});

Pour des commandes curl, ajoutez un ? à la fin du chemin, puis ajoutez le nom et la valeur de votre paramètre de requête sous la forme parameter_name=value. Séparez les paramètres de requête, quand il y en a plusieurs, par un &.

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2&sort=updated&direction=asc" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"

L’opération retourne la liste des problèmes et des données sur chaque problème. Pour plus d’informations sur l’utilisation de la réponse, consultez la section « Utilisation de la réponse ».

Utilisation de paramètres de corps

Les paramètres de corps vous permettent de passer des données supplémentaires à l’API. Par exemple, l’opération « Créer un problème » vous oblige à spécifier un titre pour le nouveau problème. Elle vous permet aussi de spécifier d’autres informations, comme le texte à placer dans le corps du problème. Pour obtenir la documentation de référence complète de cette opération, consultez « Créer un problème ».

L’opération « Créer un problème » utilise le même chemin que l’opération « Lister les problèmes d’un dépôt » mentionnée dans les exemples ci-dessus, mais elle utilise une méthode POST au lieu d’une méthode GET.

Pour GitHub CLI, utilisez l’indicateur -F pour passer un paramètre qui correspond à un nombre, une valeur booléenne ou Null. Utilisez -f pour passer des paramètres de chaîne.

Remarque : Actuellement, GitHub CLI n’accepte pas les paramètres qui correspondent à des tableaux. Pour plus d’informations, consultez ce problème.

gh api --header 'Accept: application/vnd.github+json' --method POST /repos/octocat/Spoon-Knife/issues -f title="Created with the REST API" -f body="This is a test issue created by the REST API"

Si vous utilisez un fine-grained personal access token, vous devez remplacer octocat/Spoon-Knife par un dépôt qui vous appartient ou qui appartient à une organisation dont vous êtes membre. Votre jeton doit avoir accès à ce dépôt et avoir des autorisations en lecture et écriture pour les problèmes de dépôt. Pour plus d’informations sur la création d’un dépôt, consultez « Créer un dépôt ». Pour plus d’informations sur l’octroi d’accès et d’autorisations à un fine-grained personal access token, consultez « Création d’un personal access token ».

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",
});

Si vous utilisez un fine-grained personal access token, vous devez remplacer octocat/Spoon-Knife par un dépôt qui vous appartient ou qui appartient à une organisation dont vous êtes membre. Votre jeton doit avoir accès à ce dépôt et avoir des autorisations en lecture et écriture pour les problèmes de dépôt. Pour plus d’informations sur la création d’un dépôt, consultez « Créer un dépôt ». Pour plus d’informations sur l’octroi d’accès et d’autorisations à un fine-grained personal access token, consultez « Création d’un personal access token ».

Pour des commandes curl, utilisez l’indicateur --data pour passer les paramètres de corps dans un objet JSON.

curl --request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

L’opération crée un problème et retourne des données sur le nouveau problème. Dans la réponse, recherchez l’adresse html_url de votre problème et accédez à votre problème dans le navigateur. Pour plus d’informations sur l’utilisation de la réponse, consultez la section « Utilisation de la réponse ».

Utilisation de la réponse

À propos du code et des en-têtes de réponse

Chaque requête retourne un code d’état HTTP qui indique la réussite de la réponse. Pour plus d’informations sur les codes de réponse, consultez la documentation relative aux codes d’état de la réponse HTTP MDN.

De plus, la réponse inclut des en-têtes qui fournissent d’autres détails. Les en-têtes qui commencent par X- ou x- sont propres à GitHub. Par exemple, les en-têtes x-ratelimit-remaining et x-ratelimit-reset vous indiquent le nombre de requêtes que vous pouvez effectuer pendant une période donnée.

Pour voir le code d’état et les en-têtes, utilisez l’indicateur --include ou --i quand vous envoyez votre requête.

Par exemple, cette requête :

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 --include

retourne le code de réponse et des en-têtes comme :

HTTP/2.0 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
Cache-Control: private, max-age=60, s-maxage=60
Content-Security-Policy: default-src 'none'
Content-Type: application/json; charset=utf-8
Date: Thu, 04 Aug 2022 19:56:41 GMT
Etag: W/"a63dfbcfdb73621e9d2e89551edcf9856731ced534bd7f1e114a5da1f5f73418"
Link: ; rel="next", ; rel="last"
Referrer-Policy: origin-when-cross-origin, strict-origin-when-cross-origin
Server: GitHub.com
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
Vary: Accept, Authorization, Cookie, X-GitHub-OTP, Accept-Encoding, Accept, X-Requested-With
X-Accepted-Oauth-Scopes: repo
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Github-Api-Version-Selected: 2022-08-09
X-Github-Media-Type: github.v3; format=json
X-Github-Request-Id: 1C73:26D4:E2E500:1EF78F4:62EC2479
X-Oauth-Client-Id: 178c6fc778ccc68e1d6a
X-Oauth-Scopes: gist, read:org, repo, workflow
X-Ratelimit-Limit: 15000
X-Ratelimit-Remaining: 14996
X-Ratelimit-Reset: 1659645499
X-Ratelimit-Resource: core
X-Ratelimit-Used: 4
X-Xss-Protection: 0

Dans cet exemple, le code de réponse est 200, ce qui indique que la requête est réussie.

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

Pour voir le code d’état et les en-têtes, utilisez l’indicateur --include ou --i quand vous envoyez votre requête.

Par exemple, cette requête :

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

retourne le code de réponse et des en-têtes comme :

HTTP/2 200
server: GitHub.com
date: Thu, 04 Aug 2022 20:07:51 GMT
content-type: application/json; charset=utf-8
cache-control: public, max-age=60, s-maxage=60
vary: Accept, Accept-Encoding, Accept, X-Requested-With
etag: W/"7fceb7e8c958d3ec4d02524b042578dcc7b282192e6c939070f4a70390962e18"
x-github-media-type: github.v3; format=json
link: ; rel="next", ; rel="last"
access-control-expose-headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
access-control-allow-origin: *
strict-transport-security: max-age=31536000; includeSubdomains; preload
x-frame-options: deny
x-content-type-options: nosniff
x-xss-protection: 0
referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin
content-security-policy: default-src 'none'
x-ratelimit-limit: 15000
x-ratelimit-remaining: 14996
x-ratelimit-reset: 1659645535
x-ratelimit-resource: core
x-ratelimit-used: 4
accept-ranges: bytes
content-length: 4936
x-github-request-id: 14E0:4BC6:F1B8BA:208E317:62EC2715

Dans cet exemple, le code de réponse est 200, ce qui indique que la requête est réussie.

À propos du corps de réponse

De nombreuses opérations retournent un corps de réponse. Sauf indication contraire, le corps de réponse est au format JSON. Par exemple, cette requête retourne la liste des problèmes et des données sur chacun d’eux :

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2
await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  per_page: 2,
});
curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"

Contrairement à l’API GraphQL où vous spécifiez les informations que vous voulez, l’API REST renvoie généralement plus d’informations que nécessaire. Si vous le voulez, vous pouvez analyser la réponse pour extraire des éléments spécifiques d’informations.

Par exemple, vous pouvez utiliser > pour rediriger la réponse vers un fichier :

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 > data.json

Vous pouvez ensuite utiliser jq pour obtenir le titre et l’ID d’auteur de chaque problème :

jq '.[] | {title: .title, authorID: .user.id}' data.json

Les deux commandes précédentes retournent quelque chose comme ceci :

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

Pour plus d’informations sur jq, consultez la documentation de jq et jq play.

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

Par exemple, vous pouvez utiliser > pour rediriger la réponse vers un fichier :

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

Vous pouvez ensuite utiliser jq pour obtenir le titre et l’ID d’auteur de chaque problème :

jq '.[] | {title: .title, authorID: .user.id}' data.json

Les deux commandes précédentes retournent quelque chose comme ceci :

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

Pour plus d’informations sur jq, consultez la documentation de jq et jq play.

Étapes suivantes

Cet article a montré comment lister et créer des problèmes dans un dépôt. En guise de pratique, essayez de commenter un problème, d’en modifier le titre ou de le fermer. Pour plus d’informations sur ces opérations, consultez « Créer un commentaire de problème » et « Mettre à jour un problème ».

Pour plus d’informations sur les opérations que vous pouvez utiliser, consultez la documentation de référence sur REST.