Skip to main content

Prise en main de l’API REST

Découvrez comment utiliser l’API REST GitHub.

Introduction

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

À propos des demandes adressées à l’API REST

Cette section décrit les éléments qui composent une demande d’API :

Chaque demande adressée à l’API REST inclut une méthode HTTP et un chemin d’accès. Selon le point de terminaison de l’API REST, vous devrez peut-être également spécifier des en-têtes de demande, des informations d’authentification, des paramètres de requête ou de corps.

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

Méthode HTTP

La méthode HTTP d’un point de terminaison définit le type d’action qu’il effectue sur une ressource donnée. Certaines méthodes HTTP courantes sont GET, POST, DELETE et PATCH. La documentation de référence de l’API REST fournit la méthode HTTP pour chaque point de terminaison.

Par exemple, la méthode HTTP pour le point de terminaison « Répertorier les problèmes de référentiel » est GET.

Dans la mesure du possible, l’API REST GitHub Enterprise Cloud s’efforce d’utiliser une méthode HTTP appropriée pour chaque action.

  • GET : utilisé pour récupérer des ressources.
  • POST : utilisé pour créer des ressources.
  • PATCH : utilisé pour mettre à jour les propriétés des ressources.
  • PUT : utilisé pour remplacer des ressources ou des collections de celles-ci.
  • DELETE : utilisé pour supprimer des ressources.

Chemin d’accès

Chaque point de terminaison possède un chemin d’accès. La documentation de référence de l’API REST donne le chemin d’accès pour chaque point de terminaison. Par exemple, le chemin d’accès pour le point de terminaison « Réppertorier les problèmes du référentiel » est /repos/{owner}/{repo}/issues.

Les crochets courbés {} dans un chemin d’accès réflètent des paramètres de chemin d’accès que vous avez besoin de spécifier. Les paramètres de chemin d’accès modifient le chemin d’accès du point de terminaison et sont requis dans votre demande. Par exemple, les paramètres de chemin d’accès pour le point de terminaison « Répertorier les problèmes du référentiel » sont {owner} et {repo}. Pour utiliser ce chemin d’accès dans votre demande d’API, remplacez {repo} par le nom du référentiel dans lequel vous souhaitez demander une liste de problèmes, puis remplacez {owner} par le nom du compte propriétaire du référentiel.

En-têtes

Les en-têtes fournissent des informations supplémentaires sur la demande et la réponse souhaitée. Voici quelques exemples d’en-têtes que vous pouvez utiliser dans vos demandes pour l’API REST GitHub. Pour obtenir un exemple de demande qui utilise des en-têtes, consultez « Effectuer une demande ».

Accept

La plupart des points de terminaison de l’API REST GitHub spécifient que vous devez transférer un en-tête Accept avec une valeur de application/vnd.github+json. La valeur de l’en-tête Accept est un type de média. Pour plus d’informations sur les types de médias, consultez « Types de médias ».

X-GitHub-Api-Version

Vous devez utiliser cet en-tête pour spécifier une version de l’API REST à utiliser pour votre demande. Pour plus d’informations, consultez « Versions des API ».

User-Agent

Toutes les demandes d’API doivent comprendre un en-tête User-Agent valide. L’en-tête User-Agent identifie l’utilisateur ou l’application qui effectue la demande.

Par défaut, GitHub CLI envoie un en-tête User-Agent valide. Toutefois, GitHub recommande d’utiliser votre nom d’utilisateur GitHub Enterprise Cloud ou le nom de votre application pour la valeur d’en-tête User-Agent. Cela permet à GitHub de vous contacter en cas de problème.

curl envoie par défaut un en-tête User-Agent valide. Toutefois, GitHub recommande d’utiliser votre nom d’utilisateur GitHub Enterprise Cloud ou le nom de votre application pour la valeur d’en-tête User-Agent. Cela permet à GitHub de vous contacter en cas de problème.

Si vous utilisez le Kit de développement logiciel (SDK) Octokit.js, le Kit de développement logiciel (SDK) envoie un en-tête valide User-Agent pour vous. Toutefois, GitHub recommande d’utiliser votre nom d’utilisateur GitHub Enterprise Cloud ou le nom de votre application pour la valeur d’en-tête User-Agent. Cela permet à GitHub de vous contacter en cas de problème.

L’exemple suivant est un exemple User-Agent une application nommée Awesome-Octocat-App :

User-Agent: Awesome-Octocat-App

Les demandes sans en-tête User-Agent sont rejetées. Si vous fournissez un en-tête User-Agent non valide, vous recevez une réponse 403 Forbidden.

Types de médias

Vous pouvez spécifier un ou plusieurs types de média en les ajoutant à l’en-tête Accept de votre demande. Pour plus d’informations sur l’en-tête Accept, consultez « Accept ».

les types de média spécifient le format des données que vous souhaitez consommer de l’API. Les types médias sont spécifiques aux ressources, ce qui leur permet de changer de façon indépendante et de prendre en charge des formats que d’autres ressources ne prennent pas en charge. La documentation de chaque point de terminaison de l’API REST GitHub décrit les types de média qu’il prend en charge. Pour plus d'informations, consultez « Documentation sur l’API REST GitHub ».

Les types de média les plus courants pris en charge par l’API REST GitHub sont application/vnd.github+json et application/json.

Il existe des types de média personnalisés que vous pouvez utiliser avec certains points de terminaison. Par exemple, l’API REST pour gérer validations et les demandes de tirage prennent en charge les types média diff, patch et sha. Les types de médias full, raw, text, ou html sont utilisés par d'autres points de terminaison.

Tous les types de média personnalisés pour GitHub Enterprise Cloud se présentent comme suit : application/vnd.github.PARAM+json, où PARAM est le nom du type de média. Par exemple, pour spécifier le type de média raw, vous devez utiliser application/vnd.github.raw+json.

Pour obtenir un exemple de demande qui utilise des types de média, consultez « Effectuer une demande ».

Authentification

De nombreux points de terminaison nécessitent une authentification ou retournent des informations supplémentaires si vous êtes authentifié. De plus, vous pouvez effectuer plus de requêtes par heure lorsque vous êtes authentifié.

Pour authentifier votre demande, vous devez fournir un jeton d’authenti fication avec les étendues ou autorisations requises. Il existe plusieurs façons d’obtenir un jeton : vous pouvez créer un personal access token, générer un jeton avec un GitHub App, ou utiliser le GITHUB_TOKEN intégré dans un flux de travail GitHub Actions. Pour plus d’informations, consultez « Authentification auprès de l’API REST ».

Pour obtenir un exemple de demande qui utilise un jeton d’authentification, consultez « Effectuer une demande ».

Remarque : Si vous ne souhaitez pas créer un jeton, vous pouvez utiliser GitHub CLI. GitHub CLI s’occupent de l’authentification pour vous et vous aident à assurer la sécurité de votre compte. Pour plus d’informations, consultez la version GitHub CLI de cette page.

Avertissement : traitez votre jeton d’accès de la même façon que vous traitez vos mots de passe ou d’autres informations d’identification sensibles. Pour plus d’informations, consultez « Sécuriser les informations d’identification de l’API ».

Bien que certains points de terminaison d’API REST soient accessibles sans authentification, GitHub CLI vous oblige à vous authentifier avant de pouvoir utiliser la sous-commande api pour effectuer une demande d’API. Utilisez la sous-commande auth login pour vous authentifier auprès de GitHub Enterprise Cloud. Pour plus d’informations, consultez « Effectuer une demande ».

Pour authentifier votre demande, vous devez fournir un jeton d’authenti fication avec les étendues ou autorisations requises. Il existe plusieurs façons d’obtenir un jeton : vous pouvez créer un personal access token, générer un jeton avec un GitHub App, ou utiliser le GITHUB_TOKEN intégré dans un flux de travail GitHub Actions. Pour plus d’informations, consultez « Authentification auprès de l’API REST ».

Pour obtenir un exemple de demande qui utilise un jeton d’authentification, consultez « Effectuer une demande ».

Avertissement : traitez votre jeton d’accès de la même façon que vous traitez vos mots de passe ou d’autres informations d’identification sensibles. Pour plus d’informations, consultez « Sécuriser les informations d’identification de l’API ».

Paramètres

De nombreuses méthodes d’API nécessitent ou vous permettent d’envoyer des informations supplémentaires dans des paramètres dans votre demande. Il existe quelques types de paramètres différents : paramètres de chemin d’accès, paramètres de corps et paramètres de requête.

Paramètres de chemin d’accès

Les paramètres de chemin d’accès modifient le chemin d’accès du point de terminaison. Ces paramètres sont requis dans votre demande. Pour plus d’informations, consultez « Chemin d’accès ».

Paramètres du corps

Les paramètres de corps vous permettent de passer des données supplémentaires à l’API. Ces paramètres peuvent être facultatifs ou obligatoires, en fonction du point de terminaison. Par exemple, un paramètre de corps peut vous permettre de spécifier un titre de problème pendant la création d’un nouveau problème, ou de spécifier certains paramètres durant l’activation ou de la désactivation d’une fonctionnalité. La documentation de chaque point de terminaison de l’API REST GitHub décrit les paramètres de corps qu’il prend en charge. Pour plus d'informations, consultez « Documentation sur l’API REST GitHub ».

Par exemple, le point de terminaison « Créer un problème » vous oblige à spécifier un titre pour le nouveau problème dans votre demande. Il vous permet également de spécifier éventuellement d’autres informations, telles que le texte à placer dans le corps du problème, les utilisateurs à affecter au nouveau problème ou les étiquettes à appliquer au nouveau problème. Pour obtenir un exemple de demande qui utilise des paramètres de corps, consultez « Effectuer une demande ».

Vous devez authentifier votre demande pour transférer des paramètres de corps. Pour plus d’informations, consultez « Authentification ».

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. Ces paramètres sont habituellement facultatifs. La documentation de chaque point de terminaison de l’API REST GitHub décrit tout paramètre de requête qu’il prend en charge. Pour plus d'informations, consultez « Documentation sur l’API REST GitHub ».

Par exemple, le point de terminaison « Répertorier les événements publics » retourne trente problèmes par défaut. Vous pouvez utiliser le paramètre de requête per_page pour renvoyer deux problèmes au lieu de 30. Vous pouvez utiliser le paramètre de requête page pour récupérer uniquement la première page des résultats. Pour obtenir un exemple de demande qui utilise des paramètres de requête, consultez « Effectuer une demande ».

Création d’une requête

Cette section montre comment effectuer une demande authentifiée auprès de l’API REST GitHub à l’aide de GitHub CLI.

1. Configurer

Installez GitHub CLI sur macOS, Windows ou Linux. Pour en savoir plus, consultez Installation dans le référentiel GitHub CLI.

2. S’authentifier

  1. Authentifiez-vous avec GitHub en exécutant cette commande depuis votre terminal.

    Shell
    gh auth login
    

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

  2. Suivez les invitations qui s’affichent à 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.

3. Choisissez un point de terminaison pour votre demande

  1. Choisissez un point de terminaison pour effectuer une demande. Vous pouvez explorer la documentation de l’API REST de GitHub Enterprise Cloud pour découvrir les points de terminaison que vous pouvez utiliser pour interagir avec GitHub Enterprise Cloud.

  2. Identifiez la méthode HTTP et le chemin d’accès du point de terminaison. Vous les envoyez avec votre demande. Pour plus d’informations, consultez « Méthode HTTP » et « Chemin d’accès ».

    Par exemple, le point de terminaison « Créer un problème » utilise la méthode HTTP POST et le chemin d’accès /repos/{owner}/{repo}/issues.

  3. Identifiez tous les paramètres de chemin d’accès requis. Les paramètres de chemin d’accès obligatoires apparaissent entre crochets {} dans le chemin d’accès du point de terminaison. Remplacez chaque espace réservé du paramètre par la valeur souhaitée. Pour plus d’informations, consultez « Chemin d’accès ».

    Par exemple, le point de terminaison « Créer un problème » utilise le chemin d’accès /repos/{owner}/{repo}/issues et les paramètres de chemin d’accès sont {owner} et {repo}. Pour utiliser ce chemin d’accès dans votre demande d’API, remplacez {repo} par le nom du référentiel dans lequel vous souhaitez créer un nouveau problème, puis remplacez {owner} par le nom du compte propriétaire du référentiel.

4. Effectuez une demande avec GitHub CLI

Pour effectuer votre demande d’API, utilisez la sous-commande api GitHub CLI. Pour plus d’informations, consultez la documentation sur la sous-commande GitHub CLI api.

Dans votre demande, spécifiez les optons et valeurs suivantes :

  • --methode suivie de la méthode HTTP et du chemin d’accès du point de terminaison. Pour plus d’informations, consultez « Méthode HTTP » et « Chemin d’accès ».

  • --en-tête :

    • Accept  : tranférez le type de média dans un en-tête Accept. Pour transférer plusieurs types de média dans un en-tête Accept, séparez les types de médias par une virgule : Accept: application/vnd.github+json,application/vnd.github.diff. Pour plus d’informations, consultez « Accept » et «  Types de média. »
    • X-GitHub-Api-Version  : transférez la version de l’API dans un en-tête X-GitHub-Api-Version. Pour plus d’informations, consultez « X-GitHub-Api-Version. ».
  • -f ou -F suivi de tous les paramètres de corps ou de requête au format key=value. Utilisez l’option -F pour tranférer un paramètre qui est un nombre, booléen ou nul. Utilisez l’option -f pour transférer des paramètres de chaîne.

    Certaines points de terminaison utilisent des paramètres de requête qui sont des tableaux. Pour envoyer un tableau dans la chaîne de requête, utilisez le paramètre de requête une fois par élément de tableau et ajoutez [] après le nom du paramètre de requête. Par exemple, pour fournir un tableau de deux ID de référentiel, utilisez -f repository_ids[]=REPOSITORY_A_ID -f repository_ids[]=REPOSITORY_B_ID.

    Si vous n’avez pas besoin de spécifier de paramètres de corps ou de requête dans votre demande, ignorez cette option. Pour plus d’informations, consultez « Paramètres de corps » et « Paramètres de requête ». Pour obtenir des exemples, consultez « Exemple de demande utilisant des paramètres de corps » et « Exemple de demande utilisant des paramètres de requête ».

Exemple de requête

L’exemple de demande si-après utilise le point de terminaison « Obtenir l’octocat » pour renvoyer l’octocat en tant qu’art ASCII.

Shell
gh api --method GET /octocat \
--header 'Accept: application/vnd.github+json' \
--header "X-GitHub-Api-Version: 2022-11-28"

Exemple de dmande utilisant des paramètres de requête

Le point de terminaison « Répertorier les événements publics » retourne trente problèmes par défaut. L’exemple suivant utilise le paramètre de requête per_page pour renvoyer deux problèmes au lieu de 30, et le paramètre de requête page pour récupérer uniquement la première page des résultats.

Shell
gh api --method GET /events -F per_page=2 -F page=1
--header 'Accept: application/vnd.github+json' \

Exemple de demande utilisant des paramètres de corps

L’exemple suivant utilise le point de terminaison « Créer un problème » pour créer un nouveau problème dans le référentiel octocat/Couteau à cuillère. Dans la réponse, recherchez le html_url de votre problème et accédez à votre problème dans le navigateur.

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

Cette section montre comment effectuer une demande authentifiée auprès de l’API REST GitHub à l’aide curl.

1. Configurer

Vous devez disposer de curl installé sur votre ordinateur. Pour vérifier si curl est déjà installé, exécutez curl --version sur 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 similaire à command not found: curl, cela signifie que curl n’est pas installé. Téléchargez et installez curl. Pour plus d’informations, consultez la page de téléchargement de boucle.

2. Choisissez un point de terminaison pour votre demande

  1. Choisissez un point de terminaison pour effectuer une demande. Vous pouvez explorer la documentation de l’API REST de GitHub Enterprise Cloud pour découvrir les points de terminaison que vous pouvez utiliser pour interagir avec GitHub Enterprise Cloud.

  2. Identifiez la méthode HTTP et le chemin d’accès du point de terminaison. Vous les envoyez avec votre demande. Pour plus d’informations, consultez « Méthode HTTP » et « Chemin d’accès ».

    Par exemple, le point de terminaison « Créer un problème » utilise la méthode HTTP POST et le chemin d’accès /repos/{owner}/{repo}/issues.

  3. Identifiez tous les paramètres de chemin d’accès requis. Les paramètres de chemin d’accès obligatoires apparaissent entre crochets {} dans le chemin d’accès du point de terminaison. Remplacez chaque espace réservé du paramètre par la valeur souhaitée. Pour plus d’informations, consultez « Chemin d’accès ».

    Par exemple, le point de terminaison « Créer un problème » utilise le chemin d’accès /repos/{owner}/{repo}/issues et les paramètres de chemin d’accès sont {owner} et {repo}. Pour utiliser ce chemin d’accès dans votre demande d’API, remplacez {repo} par le nom du référentiel dans lequel vous souhaitez créer un nouveau problème, puis remplacez {owner} par le nom du compte propriétaire du référentiel.

3. Créez des informations d’identification d’authentification

Créez un jeton d’accès pour authentifier votre demande. Vous pouvez enregistrer votre jeton et l’utiliser pour plusieurs demandes. Donnez au jeton toutes les étendues ou autorisations requises pour accéder au point de terminaison. Vous enverrez ce jeton dans un en-tête Authorization avec votre demande. Pour plus d’informations, consultez « Authentification ».

4. Effectuez une demande curl

Utilisez la commande curl pour effectuer votre requête. Pour plus d’informations, consultez la documentation de boucle.

Spécifiez les options et valeurs suivantes dans votre demande :

  • --request ou -X suivi de la méthode HTTP en tant que valeur. Pour plus d'informations, consultez « Méthode HTTP ».

  • --url suivi du chemin complet comme valeur. Le chemin complet est une URL qui comprend l’URL de base de l’API REST GitHub (https://api.github.com) et le chemin d’accès du point de terminaison, comme suit : https://api.github.com/PATH. Remplacez PATH par le chemin d’accès du point de terminaison. Pour plus d’informations, consultez « Chemin d’accès ».

    Pour utiliser les paramètres de requête, ajoutez un ? à la fin du chemin d’accès, puis ajoutez le nom et la valeur de votre paramètre de requête dans le formulaire parameter_name=value. Séparez les paramètres de requête, quand il y en a plusieurs, par un &. Si vous souhaitez envoyer un tableau dans la chaîne de requête, utilisez le paramètre de requête une fois par élément de tableau et ajoutez [] après le nom du paramètre de requête. Par exemple, pour fournir un tableau de deux ID de référentiel, utilisez ?repository_ids[]=REPOSITORY_A_ID&repository_ids[]=REPOSITORY_B_ID. Pour en savoir plus, voir « Paramètres des requêtes. » Pour obtenir un exemple, consultez « Exemple de demande utilisant des paramètres de requête. »

  • --header ou -H  :

    • Accept  : tranférez le type de média dans un en-tête Accept. Pour transférer plusieurs types de média dans un en-tête Accept, séparez les types de média par une virgule, par exemple : Accept: application/vnd.github+json,application/vnd.github.diff. Pour plus d’informations, consultez « Accept » et «  Types de média. »
    • X-GitHub-Api-Version  : transférez la version de l’API dans un en-tête X-GitHub-Api-Version. Pour plus d’informations, consultez « X-GitHub-Api-Version. ».
    • Authorization  : transmettez votre jeton d’authentification dans un en-tête Authorization. Sachez que dans la plupart des cas, vous pouvez utiliser Authorization: Bearer ou Authorization: token pour tranférer un jeton. Toutefois, si vous passez un jeton web JSON (JWT), vous devez utiliser Authorization: Bearer. Pour plus d’informations, consultez « Authentification ». Pour obtenir un exemple de demande qui utilise un en-tête Authorization, consultez « Exemple de demande utilisant des paramètres de corps. »
  • --data ou -d suivi de tous les paramètres de corps au sein d’un objet JSON. Si vous ne souhaitez pas spécifier de paramètres de corps dans votre demande, ignorez cette option. Pour plus d’informations, consultez « Paramètres de corps. » Pour obtenir un exemple, consultez « Exemple de demande utilisant des paramètres de corps. »

Exemple de requête

L’exemple de demande si-après utilise le point de terminaison « Obtenir l’octocat » pour renvoyer l’octocat en tant qu’art ASCII.

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

Exemple de dmande utilisant des paramètres de requête

Le point de terminaison « Répertorier les événements publics » retourne trente problèmes par défaut. L’exemple suivant utilise le paramètre de requête per_page pour renvoyer deux problèmes au lieu de 30, et le paramètre de requête page pour récupérer uniquement la première page des résultats.

Shell
curl --request GET \
--url "https://api.github.com/events?per_page=2&page=1" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/events

Exemple de demande utilisant des paramètres de corps

L’exemple suivant utilise le point de terminaison « Créer un problème » pour créer un nouveau problème dans le référentiel octocat/Couteau à cuillère. Remplacez YOUR-TOKEN par le jeton d’authentification que vous avez créé à l’étape précédente.

Remarque : si vous utilisez un fine-grained personal access token, vous devez remplacer octocat/Spoon-Knife par un référentiel 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, consultez « Gestion de vos jetons d'accès personnels ».

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

Cette section montre comment effectuer une demande à l’API REST GitHub à l’aide de JavaScript et Octokit.js. Pour obtenir un guide plus détaillé, consultez « Écriture de scripts avec l’API REST et JavaScript ».

1. Configurer

Vous devez installer octokit pour utiliser la bibliothèque Octokit.js illustrée dans les exemples suivants.

2. Choisissez un point de terminaison pour votre demande

  1. Choisissez un point de terminaison pour effectuer une demande. Vous pouvez explorer la documentation de l’API REST de GitHub Enterprise Cloud pour découvrir les points de terminaison que vous pouvez utiliser pour interagir avec GitHub Enterprise Cloud.

  2. Identifiez la méthode HTTP et le chemin d’accès du point de terminaison. Vous les envoyez avec votre demande. Pour plus d’informations, consultez « Méthode HTTP » et « Chemin d’accès ».

    Par exemple, le point de terminaison « Créer un problème » utilise la méthode HTTP POST et le chemin d’accès /repos/{owner}/{repo}/issues.

  3. Identifiez tous les paramètres de chemin d’accès requis. Les paramètres de chemin d’accès obligatoires apparaissent entre crochets {} dans le chemin d’accès du point de terminaison. Remplacez chaque espace réservé du paramètre par la valeur souhaitée. Pour plus d’informations, consultez « Chemin d’accès ».

    Par exemple, le point de terminaison « Créer un problème » utilise le chemin d’accès /repos/{owner}/{repo}/issues et les paramètres de chemin d’accès sont {owner} et {repo}. Pour utiliser ce chemin d’accès dans votre demande d’API, remplacez {repo} par le nom du référentiel dans lequel vous souhaitez créer un nouveau problème, puis remplacez {owner} par le nom du compte propriétaire du référentiel.

3. Créez un jeton d’accès

Créez un jeton d’accès pour authentifier votre demande. Vous pouvez enregistrer votre jeton et l’utiliser pour plusieurs demandes. Donnez au jeton toutes les étendues ou autorisations requises pour accéder au point de terminaison. Vous enverrez ce jeton dans un en-tête Authorization avec votre demande. Pour plus d’informations, consultez « Authentification ».

4. Effectuez une demande avec Octokit.js

  1. Importez octokit dans votre script. Par exemple : import { Octokit } from "octokit";. Pour découvrir d’autres manières d’importer octokit, consultez le fichier Lisez-moi d’Octokit.js.

  2. Créez une instance de Octokit avec votre jeton. Remplacez YOUR-TOKEN par votre jeton.

    JavaScript
    const octokit = new Octokit({ 
      auth: 'YOUR-TOKEN'
    });
    
  3. Utilisez octokit.request pour exécuter votre requête.

    • Envoyez la méthode HTTP et le chemin d’accès en tant que premier argument à la méthode request. Pour plus d’informations, consultez « Méthode HTTP » et « Chemin d’accès ».
    • Spécifiez tous les paramètres de chemin d’accès, de requête et de corps dans un objet en tant que second argument à la méthode request. Pour plus d’informations, consultez « Paramètres. »

    Dans l’exemple de demande suivant, la méthode HTTP est POST, le chemin d’accès est /repos/{owner}/{repo}/issues, les paramètres de chemin d’accès sont owner: "octocat" et repo: "Spoon-Knife", et les paramètres de corps sont title: "Created with the REST API" et body: "This is a test issue created by the REST API".

    Remarque : si vous utilisez un fine-grained personal access token, vous devez remplacer octocat/Spoon-Knife par un référentiel 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, consultez « Gestion de vos jetons d'accès personnels ».

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

    La méthode request 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 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, le code ci-après envoie un en-tête content-type avec la valeur de text/plain et un en-tête X-GitHub-Api-Version avec la valeur de 2022-11-28.

    JavaScript
    await octokit.request("GET /octocat", {
      headers: {
        "content-type": "text/plain",
        "X-GitHub-Api-Version": "2022-11-28",
      },
    });
    

Utilisation de la réponse

après avoir effectuer une demande, 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.

À 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 visualiser le code d’état et les en-têtes, utilisez l’option --include ou --i quand vous envoyez votre demande.

Par exemple, cette demande obtient une liste de problèmes dans le référentiel octocat/Couteau à cuillère :

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

Et elle retourne un code de réponse et des en-têtes qui ressemblent à ceci :

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: <https://api.github.com/repositories/1300192/issues?per_page=1&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=1&page=14817>; 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.

Dans l’exemple suivant, remplacez REPO-OWNER par le nom du compte propriétaire du référentiel et REPO-NAME par le nom du référentiel.

JavaScript
try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    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 visualiser le code d’état et les en-têtes, utilisez l’option --include ou --i quand vous envoyez votre demande.

Par exemple, cette demande obtient une liste de problèmes dans le référentiel octocat/Couteau à cuillère :

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

Et elle retourne un code de réponse et des en-têtes qui ressemblent à ceci :

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: <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=7409>; 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 nombreux points de terminaison retournent un corps de réponse. Sauf indication contraire, le corps de réponse est au format JSON. Les champs vierges sont inclus comme null au lieu d’être omis. Tous les horodateurs reviennent en temps UTC, format ISO 8601 : YYYY-MM-DDTHH:MM:SSZ.

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. Dans l’exemple suivant, remplacez REPO-OWNER par le nom du compte propriétaire du référentiel et REPO-NAME par le nom du référentiel.

Shell
gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/REPO-OWNER/REPO-NAME/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 :

Shell
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.

Par exemple, vous pouvez obtenir le titre et l’ID d’auteur de chaque problème. Dans l’exemple suivant, remplacez REPO-OWNER par le nom du compte propriétaire du référentiel et REPO-NAME par le nom du référentiel.

JavaScript
try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    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. Dans l’exemple suivant, remplacez REPO-OWNER par le nom du compte propriétaire du référentiel et REPO-NAME par le nom du référentiel.

Shell
curl --request GET \
--url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/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 :

Shell
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.

Représentations détaillées ou résumées

Une réponse peut comprendre tous les attributs d’une ressource ou seulement un sous-ensemble d’attributs, selon que vous récupérez une ressource individuelle ou une liste de ressources.

  • Quand vous récupérez une ressource individuelle, notamment un référentiel spécifique, la réponse comprend généralement tous les attributs de cette ressource. Il s’agit de la représentation « détaillée » de la ressource.
  • Quand vous récupérez une liste de ressources, comme une liste de plusieurs référentiels, la réponse comprend uniquement un sous-ensemble des attributs pour chaque ressource. Il s’agit de la représentation « récapitulative » de la ressource.

Sachez que l’autorisation influe parfois sur quantité de détail comprise dans la représentation.

La raison en est que certains attributs sont coûteux en calcul pour l’API,, donc GitHub exclut ces attributs de la représentation de résumé. POur obtenir ces attributs, vous pouvez récupérez la représentation détaillée.

La documentation fournit un exemple de réponse pour chaque méthode d’API. L’exemple de réponse illustre tous les attributs retournés par cette méthode.

Hypermédia

Toutes les ressources peuvent comporter une ou plusieurs propriétés *_url liées à d’autres ressources. Ces propriétés visent à fournir des URL explicites afin d’éviter aux clients d’API appropriés d’avoir à construire des URL eux-mêmes. Il est vivement recommandé aux clients d’API de les utiliser. Cela facilite les mises à niveau futures de l’API pour les développeurs. Toutes les URL doivent représenter des modèles d’URI RFC 6570 appropriés.

Vous pouvez ensuite développer ces modèles à l’aide de la gemme uri_template ou d’un objet similaire :

>> tmpl = URITemplate.new('/notifications{?since,all,participating}')
>> tmpl.expand
=> "/notifications"

>> tmpl.expand all: 1
=> "/notifications?all=1"

>> tmpl.expand all: 1, participating: 1
=> "/notifications?all=1&participating=1"

É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, consultez un point de terminaison « Créer un commentaire de problème » et le point de terminaison « Mettre à jour un problème ».

Pour plus d’informations sur d’autres points de terminaison que vous pouvez utiliser, consultez la documentation de référence REST.