Prise en main de l’API REST

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 :

• Méthode HTTP
• Chemin d’accès
• 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 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.

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

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

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

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

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