À 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 de 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 GitHub, consultez « À propos des API 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 « Meta ».
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
. Définissez l’URL de base sur http(s)://HOSTNAME/api/v3
. Remplacez [hostname]
par le nom de votre instance GitHub Enterprise Server.
const octokit = new Octokit({
baseUrl: "http(s)://HOSTNAME/api/v3",
});
Ensuite, utilisez la méthode request
pour effectuer des requêtes. Passez la méthode HTTP et le chemin en tant que premier argument.
await octokit.request("GET /octocat", {});
Ajoutez l’URL de base de l’API REST GitHub, http(s)://HOSTNAME/api/v3
, au début du chemin pour obtenir l’URL complète : http(s)://HOSTNAME/api/v3/octocat
. Remplacez [hostname]
par le nom de votre instance GitHub Enterprise Server.
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é.
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. Les autres opérations peuvent nécessiter d’autres étendues. Pour plus d’informations sur la création d’un personal access token, consultez « Gestion de vos jetons d’accès personnels ».
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 « Inscription d’une application GitHub », « À propos de l’authentification avec une application GitHub » et « Authentification auprès d’une application GitHub pour le compte d’un utilisateur ».
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 par jeton automatique ».
Pour plus d’informations sur les bonnes pratiques que vous pouvez utiliser pour sécuriser vos jetons, consultez « Keeping your API credentials secure ».
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 ».
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. Remplacez [hostname]
par le nom de votre instance GitHub Enterprise Server.
const octokit = new Octokit({
baseUrl: "http(s)://HOSTNAME/api/v3",
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.
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 « Workflow syntax for 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 par jeton automatique ». 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 « Workflow syntax for GitHub Actions ».
GitHub vous recommande de vous authentifier avec le jeton GITHUB_TOKEN
intégré au lieu de créer un jeton. Si ce n’est pas possible, stockez votre jeton sous forme de secret et remplacez GITHUB_TOKEN
dans l’exemple ci-dessous par le nom de votre secret. Pour plus d’informations sur GITHUB_TOKEN
, consultez « Authentification par jeton automatique ». Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ».
L’exemple de workflow suivant effectue ceci :
- Il extrait le contenu du dépôt.
- Il configure Node.js.
- Il installe
octokit
. - Il stocke la valeur de
GITHUB_TOKEN
sous forme de variable d’environnement appeléeTOKEN
et exécute.github/actions-scripts/use-the-api.mjs
, qui peut accéder à cette variable d’environnement en tant queprocess.env.TOKEN
.
Exemple de workflow :
on:
workflow_dispatch:
jobs:
use_api_via_script:
runs-on: ubuntu-latest
permissions: {}
steps:
- name: Check out repo content
uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: '16.17.0'
cache: npm
- name: Install dependencies
run: npm install octokit
- name: Run script
env:
TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
node .github/actions-scripts/use-the-api.mjs
Exemple de script JavaScript, avec le chemin de fichier .github/actions-scripts/use-the-api.mjs
:
import { Octokit } from "octokit";
const octokit = new Octokit({
baseUrl: "http(s)://HOSTNAME/api/v3",
auth: process.env.TOKEN,
});
await octokit.request("GET /octocat", {});
Au lieu de stocker votre script dans un fichier distinct et de l’exécuter à partir de votre workflow, vous pouvez utiliser l’action actions/github-script
pour exécuter un script. Pour plus d’informations, consultez le fichier Lisez-moi actions/github-script.
jobs:
use_api_via_script:
runs-on: ubuntu-latest
permissions: {}
steps:
- uses: actions/github-script@v6
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
script: |
await github.request('GET /octocat', {})
Vous pouvez aussi utiliser le mot clé run
pour exécuter des commandes curl
dans vos workflows GitHub Actions. Pour plus d’informations, consultez « Workflow syntax for GitHub Actions ».
GitHub vous recommande de vous authentifier avec le jeton GITHUB_TOKEN
intégré au lieu de créer un jeton. Si ce n’est pas possible, stockez votre jeton sous forme de secret et remplacez GITHUB_TOKEN
dans l’exemple ci-dessous par le nom de votre secret. Pour plus d’informations sur GITHUB_TOKEN
, consultez « Authentification par jeton automatique ». Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ».
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' --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",
},
});
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"
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 obtenir la documentation de référence de cette opération, consultez « Problèmes ».
Remarque : Pour que cette commande fonctionne pour votre instance GitHub Enterprise Server, remplacez octocat/Spoon-Knife
par un dépôt appartenant à votre instance GitHub Enterprise Server. Sinon, réexécutez la commande gh auth login
pour vous authentifier auprès de GitHub.com au lieu de votre instance GitHub Enterprise Server.
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
Remarque : Pour que cet exemple fonctionne pour votre instance GitHub Enterprise Server, remplacez octocat/Spoon-Knife
par un dépôt appartenant à votre instance GitHub Enterprise Server. Sinon, créez une instance de Octokit
et ne spécifiez pas baseURL
.
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
.
Remarque : Si vous voulez utiliser votre instance GitHub Enterprise Server au lieu de GitHub.com, utilisez http(s)://HOSTNAME/api/v3
au lieu de https://api.github.com
et remplacez [hostname]
par le nom de votre instance GitHub Enterprise Server. Remplacez octocat/Spoon-Knife
par un dépôt appartenant à votre instance GitHub Enterprise Server.
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 « Problèmes ».
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"
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",
});
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.
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.
É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 « Problèmes » et « Problèmes ».
Pour plus d’informations sur les opérations que vous pouvez utiliser, consultez la documentation de référence sur REST.