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 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 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 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 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 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 ».
Note
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.
Warning
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. 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 ».
Warning
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
-
Pour vous authentifier sur GitHub, exécutez la commande suivante depuis votre terminal.
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 CLIauth login
. -
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
).
-
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
etgit pull
, sans avoir à configurer un gestionnaire d'informations d'identification distinct ou à utiliser SSH.
3. Choisissez un point de terminaison pour votre demande
-
Choisissez un point de terminaison pour effectuer une demande. Vous pouvez explorer la documentation de l’API REST de GitHub pour découvrir les points de terminaison que vous pouvez utiliser pour interagir avec GitHub.
-
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
. -
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
: transmettez le type de média dans unAccept
en-tête. Pour transférer plusieurs types de média dans un en-têteAccept
, 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édias ».X-GitHub-Api-Version
: transmettez la version de l’API dans unX-GitHub-Api-Version
en-tête. 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 formatkey=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.
gh api --method GET /octocat \ --header 'Accept: application/vnd.github+json' \ --header "X-GitHub-Api-Version: 2022-11-28"
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.
gh api --method GET /events -F per_page=2 -F page=1 --header 'Accept: application/vnd.github+json' \
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.
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' \
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 quecurl
est installé. - Si vous recevez un message similaire à
command not found: curl
, cela signifie quecurl
n’est pas installé. Téléchargez et installezcurl
. Pour plus d’informations, consultez la page de téléchargement de boucle.
2. Choisissez un point de terminaison pour votre demande
-
Choisissez un point de terminaison pour effectuer une demande. Vous pouvez explorer la documentation de l’API REST de GitHub pour découvrir les points de terminaison que vous pouvez utiliser pour interagir avec GitHub.
-
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
. -
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 de GitHub (https://api.github.com
) et le chemin du point de terminaison, comme ceci :https://api.github.com/PATH
. Remplacer par le chemin d'accès au 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 formulaireparameter_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
: transmettez le type de média dans unAccept
en-tête. Pour transférer plusieurs types de média dans un en-têteAccept
, 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édias ».X-GitHub-Api-Version
: transmettez la version de l’API dans unX-GitHub-Api-Version
en-tête. Pour plus d’informations, consultez «X-GitHub-Api-Version
».Authorization
: transmettez votre jeton d’authentification dans unAuthorization
en-tête. Sachez que dans la plupart des cas, vous pouvez utiliserAuthorization: Bearer
ouAuthorization: token
pour tranférer un jeton. Toutefois, si vous passez un jeton web JSON (JWT), vous devez utiliserAuthorization: Bearer
. Pour plus d’informations, consultez « Authentification ». Pour obtenir un exemple de demande qui utilise un en-têteAuthorization
, 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.
curl --request GET \ --url "https://api.github.com/octocat" \ --header "Accept: application/vnd.github+json" \ --header "X-GitHub-Api-Version: 2022-11-28"
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.
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
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.
Note
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 ».
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" }'
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.
- Installez
octokit
. Par exemple :npm install octokit
. Pour découvrir d’autres manières d’installer ou chargeroctokit
, consultez le fichier Lisez-moi d’Octokit.js.
2. Choisissez un point de terminaison pour votre demande
-
Choisissez un point de terminaison pour effectuer une demande. Vous pouvez explorer la documentation de l’API REST de GitHub pour découvrir les points de terminaison que vous pouvez utiliser pour interagir avec GitHub.
-
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
. -
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
-
Importez
octokit
dans votre script. Par exemple :import { Octokit } from "octokit";
. Pour découvrir d’autres manières d’importeroctokit
, consultez le fichier Lisez-moi d’Octokit.js. -
Créez une instance de
Octokit
avec votre jeton. RemplacezYOUR-TOKEN
par votre jeton.JavaScript const octokit = new Octokit({ auth: 'YOUR-TOKEN' });
const octokit = new Octokit({ auth: 'YOUR-TOKEN' });
-
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 sontowner: "octocat"
etrepo: "Spoon-Knife"
, et les paramètres de corps sonttitle: "Created with the REST API"
etbody: "This is a test issue created by the REST API"
.Note
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", });
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êteAccept: application/vnd.github+json
. Pour passer des en-têtes supplémentaires ou un en-têteAccept
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 detext/plain
et un en-têteX-GitHub-Api-Version
avec la valeur de2022-11-28
.JavaScript await octokit.request("GET /octocat", { headers: { "content-type": "text/plain", "X-GitHub-Api-Version": "2022-11-28", }, });
await octokit.request("GET /octocat", { headers: { "content-type": "text/plain", "X-GitHub-Api-Version": "2022-11-28", }, });
- Envoyez la méthode HTTP et le chemin d’accès en tant que premier argument à la méthode
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-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, 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.
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}`) }
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-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.
gh api \ --header 'Accept: application/vnd.github+json' \ --method GET /repos/REPO-OWNER/REPO-NAME/issues \ -F per_page=2 > data.json
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 :
jq '.[] | {title: .title, authorID: .user.id}' data.json
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.
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}`) }
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.
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
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 :
jq '.[] | {title: .title, authorID: .user.id}' data.json
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.