Prise en main de l’API REST

Introduction

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

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

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

• Méthode HTTP
• Chemin
• En-têtes
• Types de médias
• Authentification
• Paramètres

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 , , et . 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 .

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

•  : utilisé pour récupérer des ressources.
•  : utilisé pour créer des ressources.
•  : utilisé pour mettre à jour les propriétés des ressources.
•  : utilisé pour remplacer des ressources ou des collections de celles-ci.
•  : 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 .

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 et . Pour utiliser ce chemin d’accès dans votre demande d’API, remplacez par le nom du référentiel dans lequel vous souhaitez demander une liste de problèmes, puis remplacez 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 avec une valeur de . La valeur de l’en-tête 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 « AUTOTITLE ».

User-Agent

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

Voici un exemple pour une application nommée :

User-Agent: Awesome-Octocat-App

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

Types de médias

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

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

Les types de média les plus courants pris en charge par l’API REST GitHub sont et .

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 les commits et les requêtes de tirage prend en charge les types de médias , et . Les types de médias , , ou sont utilisés par d'autres points de terminaison.

Tous les types de média personnalisés pour GitHub se présentent comme suit : , où est le nom du type de média. Par exemple, pour spécifier le type de média , vous devez utiliser .

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

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

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

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 transmettre des paramètres dans le corps de la requête. 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 AUTOTITLE.

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 pour renvoyer deux problèmes au lieu de 30. Vous pouvez utiliser le paramètre de requête 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

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"

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' \

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' \

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"

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

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"
}'

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 plus de détails concernant la réponse. Les en-têtes qui commencent par ou sont propres à GitHub. Par exemple, les en-têtes et vous indiquent le nombre de requêtes que vous pouvez effectuer pendant une période donnée.

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

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

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

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

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

À propos du corps de réponse

De nombreux endpoints retournent un corps de réponse. Sauf indication contraire, le corps de réponse est au format JSON. Les champs vides sont inclus avec la valeur au lieu d’être omis. Tous les horodateurs reviennent en temps UTC, format ISO 8601 : .

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.

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

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

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

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

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

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

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

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

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

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érer 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 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 les points de terminaison « Créer un commentaire de problème » et « 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.