Skip to main content

Ressources disponibles dans l’API REST

Découvrez comment parcourir les ressources fournies par l’API GitHub.

Version de l'API

Les ressources disponibles peuvent varier selon les versions de l’API REST. Vous devez utiliser l’en-tête X-GitHub-Api-Version pour spécifier une version d’API. Pour plus d’informations, consultez « Versions d’API ».

schéma

Tout l’accès à l’API se fait par HTTPS et à partir de https://api.github.com. Toutes les données sont envoyées et reçues au format JSON.

$ curl -I https://api.github.com/users/octocat/orgs

> HTTP/2 200
> Server: nginx
> Date: Fri, 12 Oct 2012 23:33:14 GMT
> Content-Type: application/json; charset=utf-8
> ETag: "a00049ba79152d03380c34652f2cb612"
> X-GitHub-Media-Type: github.v3
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4987
> x-ratelimit-reset: 1350085394
> Content-Length: 5
> Cache-Control: max-age=0, private, must-revalidate
> X-Content-Type-Options: nosniff

Les champs vides sont inclus avec la valeur null au lieu d’être omis.

Tous les horodatages sont retournés au format UTC ISO 8601 :

YYYY-MM-DDTHH:MM:SSZ

Pour plus d’informations sur les fuseaux horaires dans les horodatages, consultez cette section.

Représentations récapitulatives

Lorsque vous récupérez une liste de ressources, la réponse inclut un sous-ensemble des attributs de cette ressource. Il s’agit de la représentation « récapitulative » de la ressource. (Certains attributs sont coûteux en calcul pour l’API. Pour des raisons de performances, ils sont exclus de la représentation récapitulative. Récupérez la représentation « détaillée » pour les obtenir.)

Exemple : Lorsque vous demandez la liste des référentiels, vous obtenez la représentation récapitulative de chaque référentiel. Ici, nous récupérons la liste des référentiels appartenant à l’organisation octokit :

GET /orgs/octokit/repos

Représentations détaillées

Lorsque vous récupérez une ressource individuelle, la réponse inclut généralement tous les attributs de cette ressource. Il s’agit de la représentation « détaillée » de la ressource. (Notez que l’autorisation influe parfois sur le niveau de détail de la représentation.)

Exemple : Lorsque vous demandez un référentiel individuel, vous obtenez sa représentation détaillée. Ici, nous récupérons le référentiel octokit/octokit.rb :

GET /repos/octokit/octokit.rb

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.

Authentification

Il existe deux façons de s’authentifier par le biais de l’API REST GitHub. Les demandes exigeant une authentification retournent 404 Not Found, au lieu de 403 Forbidden, dans certains endroits. Cela permet d’éviter les fuites accidentelles de référentiels privés auprès d’utilisateurs non autorisés.

Authentification de base

$ curl -u "username" https://api.github.com

Jeton OAuth2 (envoyé dans un en-tête)

$ curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.github.com

Remarque : GitHub recommande d’envoyer des jetons OAuth à l’aide de l’en-tête d’autorisation.

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.

En savoir plus sur OAuth2. Notez que les jetons OAuth2 peuvent être obtenus à l’aide du flux d’application web pour les applications de production.

Clé/secret OAuth2

Avis de désapprobation : GitHub va interrompre le mode d’authentification auprès de l’API à l’aide des paramètres de requête. L’authentification auprès de l’API doit être effectuée au moyen de l’Authentification HTTP de base. L’utilisation des paramètres de requête pour s’authentifier auprès de l’API ne fonctionnera plus à partir du 5 mai 2021. Pour plus d’informations, notamment sur les baisses de tension planifiées, consultez le billet de blog.

curl -u my_client_id:my_client_secret 'https://api.github.com/user/repos'

L’utilisation de client_id et de client_secret ne permet pas de vous authentifier en tant qu’utilisateur, mais seulement d’identifier votre application OAuth pour augmenter votre limite de débit. Les autorisations sont accordées uniquement aux utilisateurs, et non aux applications. Vous ne récupérerez que les données qu’un utilisateur non authentifié verrait. C’est pourquoi la clé et le secret OAuth2 doivent être utilisés exclusivement dans les scénarios de serveur à serveur. Ne communiquez pas la clé secrète client de votre application OAuth à vos utilisateurs.

En savoir plus sur la limitation de débit non authentifiée.

Limite d’échecs de connexion

L’authentification avec des informations d’identification non valides retourne 401 Unauthorized :

$ curl -I https://api.github.com -u foo:bar
> HTTP/2 401

> {
>   "message": "Bad credentials",
>   "documentation_url": "https://docs.github.com/rest"
> }

En cas de détection de plusieurs demandes comportant des informations d’identification non valides dans un court délai, l’API rejette temporairement toutes les tentatives d’authentification de l’utilisateur (y compris celles qui contiennent des informations d’identification valides) avec 403 Forbidden :

$ curl -i https://api.github.com -u 
-u VALID_USERNAME:VALID_TOKEN 
> HTTP/2 403
> {
>   "message": "Maximum number of login attempts exceeded. Please try again later.",
>   "documentation_url": "https://docs.github.com/rest"
> }

Paramètres

De nombreuses méthodes API prennent des paramètres facultatifs. Pour les demandes GET, tous les paramètres non spécifiés en tant que segment dans le chemin peuvent être transmis sous la forme d’un paramètre de chaîne de requête HTTP :

$ curl -i "https://api.github.com/repos/vmg/redcarpet/issues?state=closed"

Dans cet exemple, les valeurs « vmg » et « redcarpet » sont fournies pour les paramètres :owner et :repo du chemin alors que :state est passé dans la chaîne de requête.

Pour les demandes POST, PATCH, PUT et DELETE, les paramètres non inclus dans l’URL doivent être codés en tant que JSON avec le Content-Type « application/json » :

$ curl -i -u username -d '{"scopes":["repo_deployment"]}' https://api.github.com/authorizations

Point de terminaison racine

Vous pouvez émettre une demande GET au point de terminaison racine pour obtenir toutes les catégories de points de terminaison prises en charge par l’API REST :

$ curl 
-u USERNAME:TOKEN https://api.github.com

ID de nœud global GraphQL

Pour savoir comment trouver les node_id au moyen de l’API REST et les utiliser dans les opérations GraphQL, consultez le guide « Utilisation des ID de nœud globaux ».

Erreurs de client

Il existe trois types possibles d’erreurs clientes sur les appels d’API qui reçoivent des corps de demande :

  1. L’envoi de JSON non valide entraîne une réponse 400 Bad Request.

    HTTP/2 400
    Content-Length: 35
    
    {"message":"Problems parsing JSON"}
    
  2. L’envoi du mauvais type de valeurs JSON entraîne une réponse 400 Bad Request.

     HTTP/2 400
     Content-Length: 40
    
     {"message":"Body should be a JSON object"}
    
  3. L’envoi de champs non valides entraîne une réponse 422 Unprocessable Entity.

    HTTP/2 422
    Content-Length: 149
    
    {
      "message": "Validation Failed",
      "errors": [
        {
          "resource": "Issue",
          "field": "title",
          "code": "missing_field"
        }
      ]
    }
    

Tous les objets d’erreur possèdent des propriétés de ressource et de champ qui permettent au client d’identifier le problème. Il existe également un code d’erreur indiquant ce qui est incorrect dans le champ. Voici les codes d’erreur de validation possibles :

Nom du code d’erreurDescription
missingUne ressource n’existe pas.
missing_fieldUn champ obligatoire sur une ressource n’a pas été défini.
invalidLa mise en forme d’un champ n’est pas valide. Pour plus d’informations, consultez la documentation.
already_existsUne autre ressource possède la même valeur que ce champ. Cela peut se produire dans les ressources qui doivent disposer d’une clé unique (par exemple les noms d’étiquette).
unprocessableLes entrées fournies ne sont pas valides.

Les ressources peuvent également envoyer des erreurs de validation personnalisées (où code a la valeur custom). Les erreurs personnalisées présentent toujours un champ message décrivant l’erreur. La plupart des erreurs incluent également un champ documentation_url pointant vers un contenu susceptible de vous aider à résoudre l’erreur.

Redirections HTTP

L’API REST GitHub utilise la redirection HTTP le cas échéant. Les clients doivent partir du principe que toute demande peut entraîner une redirection. La réception d’une redirection HTTP ne constitue pas une erreur ; les clients doivent suivre cette redirection. Les réponses de redirection comportent un champ d’en-tête Location qui contient l’URI de la ressource à laquelle le client doit répéter les demandes.

Code d’étatDescription
301Redirection permanente. L’URI que vous avez utilisé pour effectuer la demande a été remplacé par celui spécifié dans le champ d’en-tête Location. Cette demande et toutes les suivantes qui seront envoyées à cette ressource doivent être dirigées vers le nouvel URI.
302, 307Redirection temporaire. La demande doit être répétée telle quelle dans l’URI spécifié dans le champ d’en-tête Location, mais les clients doivent continuer à utiliser l’URI d’origine pour les demandes futures.

D’autres codes d’état de redirection peuvent être utilisés conformément à la spécification HTTP 1.1.

Verbes HTTP

Dans la mesure du possible, l’API REST GitHub s’efforce d’utiliser les verbes HTTP appropriés pour chaque action. Notez que les verbes HTTP respectent la casse.

VerbeDescription
HEADPeut être émis sur n’importe quelle ressource pour obtenir uniquement les informations d’en-tête HTTP.
GETUtilisé pour récupérer des ressources.
POSTUtilisé pour créer des ressources.
PATCHUtilisé pour mettre à jour des ressources avec des données JSON partielles. Par exemple, une ressource Issue comporte des attributs title et body. Une demande PATCH peut accepter un ou plusieurs attributs pour mettre à jour la ressource.
PUTUtilisé pour remplacer des ressources ou des collections. Pour les demandes PUT dépourvues d’attribut body, veillez à définir l’en-tête Content-Length sur zéro.
DELETEUtilisé pour supprimer des ressources.

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"

Pagination

Lorsqu’une réponse de l’API REST inclut de nombreux résultats, GitHub les pagine et en retourne une partie. Vous pouvez utiliser l’en-tête de lien de la réponse pour demander des pages de données supplémentaires. Si un point de terminaison prend en charge le paramètre de requête per_page, vous pouvez contrôler le nombre de résultats retournés sur une page. Pour plus d’informations sur la pagination, consultez « Utilisation de la pagination dans l’API REST ».

Délais d'attente

Si GitHub prend plus de 10 secondes pour traiter une demande d’API, GitHub met fin à la demande et vous recevrez une réponse d’expiration du délai d’attente semblable à la suivante :

{
    "message": "Server Error"
}

GitHub se réserve le droit de modifier le délai d’expiration pour protéger la vitesse et la fiabilité de l’API.

Limitation du débit

L’API GitHub utilise la limitation du débit pour contrôler le trafic d’API. Les différents types de demandes d’API ont des limites de débit différentes. Les en-têtes de réponse décrivent l’état actuel de votre limite de débit.

Limites du taux de transfert

Les limites de débit varient selon les types de demandes d’API envoyés à GitHub.com. En outre, les points de terminaison de recherche ont des limites dédiées. Pour plus d’informations, consultez « Recherche » dans la documentation de l’API REST.

Limites de débit pour les demandes provenant de comptes personnels

Les demandes d’API directes que vous authentifiez avec un personal access token sont des demandes d’utilisateur à serveur. Une application OAuth ou une application GitHub peut également effectuer une demande d’utilisateur à serveur en votre nom après avoir autorisé l’application. Pour plus d’informations, consultez « Création d’un personal access token », « Autorisation des applications OAuth » et « Autorisation des applications GitHub ».

GitHub associe toutes les demandes d’utilisateur à serveur à l’utilisateur authentifié. Dans le cas des applications OAuth et GitHub, il s’agit de l’utilisateur qui a autorisé l’application. Toutes les demandes d’utilisateur à serveur sont comptabilisées par rapport à la limite de débit de l’utilisateur authentifié.

Utilisateur à serveur sont limitées à 5 000 requêtes par heure et par utilisateur authentifié. Toutes les requêtes provenant d’applications OAuth autorisées par un utilisateur ou un personal access token appartenant à cet utilisateur, ainsi que les requêtes authentifiées à l’aide des informations d’identification d’authentification de l’utilisateur, partagent le même quota de 5 000 requêtes par heure pour cet utilisateur.

Les requêtes utilisateur à serveur sont soumises à une limite plus élevée de 15 000 requêtes par heure et par utilisateur authentifié dans les scénarios suivants.

  • La requête provient d’une GitHub App qui appartient à une organisation GitHub Enterprise Cloud.
  • La requête provient d’une OAuth App qui appartient à ou est approuvée par une organisation GitHub Enterprise Cloud.

Pour les demandes non authentifiées, la limite de débit autorise jusqu’à 60 demandes par heure. Les demandes non authentifiées sont associées à l’adresse IP d’origine, et non à la personne qui les effectue.

Limites de débit pour les demandes provenant de GitHub Apps

Les demandes d’une application GitHub peuvent être des demandes d’utilisateur à serveur ou de serveur à serveur. Pour plus d’informations sur les limites de débit des applications GitHub, consultez « Limites de débit des applications GitHub ».

Limites de débit pour les demandes provenant de GitHub Actions

Vous pouvez utiliser le jeton GITHUB_TOKEN intégré pour authentifier les demandes dans des flux de travail GitHub Actions. Pour plus d’informations, consultez « Authentification automatique par jeton ».

Avec GITHUB_TOKEN, la limite de débit s’élève à 1 000 demandes par heure et par dépôt. Pour les demandes adressées à des ressources appartenant à un compte d’entreprise sur GitHub.com, la limite de débit de GitHub Enterprise Cloud s’applique, soit 15 000 demandes par heure et par dépôt.

Vérification de l’état de la limite de débit

Les en-têtes de réponse décrivent l’état actuel de votre limite de débit. Vous pouvez également utiliser l’API REST pour rechercher le nombre actuel d’appels d’API disponibles pour vous ou votre application à tout moment.

En-têtes de limite de débit

Les en-têtes de réponse x-ratelimit décrivent l’état actuel de votre limite de débit après chaque demande :

$ curl -i https://api.github.com/users/octocat
> HTTP/2 200
> x-ratelimit-limit: 60
> x-ratelimit-remaining: 56
> x-ratelimit-used: 4
> x-ratelimit-reset: 1372700873
Nom de l’en-têteDescription
x-ratelimit-limitNombre maximal de demandes autorisées par heure.
x-ratelimit-remainingNombre de demandes restantes dans la fenêtre de limite de débit actuelle.
x-ratelimit-usedNombre de demandes que vous avez faites dans la fenêtre de limite de débit actuelle.
x-ratelimit-resetHeure à laquelle la fenêtre de limite de débit actuelle se réinitialise en secondes d’époque UTC.

Vérification de l’état de votre limite de débit avec l’API REST

Vous pouvez utiliser l’API REST pour vérifier l’état de votre limite de débit sans avoir à atteindre la limite actuelle. Pour plus d’informations, consultez « Limite de débit ». Lorsque cela est possible, GitHub recommande d’utiliser plutôt les en-têtes de réponse x-ratelimit afin de réduire la charge sur l’API.

Dépassement de la limite de débit

Si vous dépassez la limite de débit, la réponse aura un état 403, et l’en-tête x-ratelimit-remaining sera 0 :

> HTTP/2 403
> Date: Tue, 20 Aug 2013 14:50:41 GMT
> x-ratelimit-limit: 60
> x-ratelimit-remaining: 0
> x-ratelimit-used: 60
> x-ratelimit-reset: 1377013266

> {
>    "message": "API rate limit exceeded for xxx.xxx.xxx.xxx. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
>    "documentation_url": "https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting"
> }

Si votre taux est limité, vous ne devez pas essayer votre demande avant l’heure spécifiée par l’heure x-ratelimit-reset.

Augmentation de la limite de débit non authentifié des applications OAuth

Si votre application OAuth doit effectuer des appels non authentifiés avec une limite de débit plus élevée, vous pouvez transmettre l’ID client et le secret de votre application avant l’itinéraire du point de terminaison.

$ curl -u my_client_id:my_client_secret -I https://api.github.com/user/repos
> HTTP/2 200
> Date: Mon, 01 Jul 2013 17:27:06 GMT
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4966
> x-ratelimit-used: 34
> x-ratelimit-reset: 1372700873

Remarque : Ne partagez jamais votre secret client avec quiconque. Ne l’incluez pas dans le code du navigateur côté client. Utilisez la méthode indiquée ici uniquement pour les appels de serveur à serveur.

Respect de la limite de débit

Si vous dépassez votre limite de débit en utilisant une authentification de base ou OAuth, vous avez de grandes chances de résoudre le problème en mettant en cache les réponses de l’API et en utilisant des demandes conditionnelles.

Limites de débit secondaires

Les limites de débit décrites ci-dessus s’appliquent à l’ensemble de l’API REST, et s’appliquent par utilisateur ou par application. Pour fournir un service de qualité sur GitHub, des limites de débit supplémentaires peuvent s’appliquer à certaines actions en cas d’utilisation de l’API. Par exemple, le fait d’utiliser l’API pour créer rapidement du contenu, réaliser des interrogations agressives au lieu d’utiliser des webhooks, effectuer plusieurs demandes simultanées ou demander à plusieurs reprises des données coûteuses en calcul peut entraîner une limitation de débit supplémentaire.

Ces limites de débit supplémentaires ne sont pas destinées à interférer avec l’utilisation légitime de l’API. Vos limites normales de débit doivent constituer la seule limite que vous ciblez. Pour vous assurer d’adopter le bon comportement vis-à-vis de l’API, consultez nos Recommandations de meilleures pratiques.

Si votre application déclenche une limite de débit supplémentaire, vous recevrez une réponse informative :

> HTTP/2 403
> Content-Type: application/json; charset=utf-8
> Connection: close

> {
>   "message": "You have exceeded a secondary rate limit and have been temporarily blocked from content creation. Please retry your request again later.",
>   "documentation_url": "https://docs.github.com/rest/overview/resources-in-the-rest-api#secondary-rate-limits"
> }

Vous devez attendre et réessayer votre demande après quelques minutes. Si l’en-tête de réponse retry-after est présent, vous ne devez pas réessayer votre demande avant le nombre de secondes spécifié. Sinon, vous ne devez pas réessayer votre demande avant la durée spécifiée par l’en-tête x-ratelimit-reset (en secondes UTC).

Agent utilisateur requis

Toutes les demandes d’API DOIVENT inclure un en-tête User-Agent valide. Les demandes sans en-tête User-Agent sont rejetées. Nous vous demandons d’utiliser votre nom d’utilisateur GitHub ou le nom de votre application comme valeur d’en-tête User-Agent. Cela nous permet de vous contacter en cas de problème.

Voici un exemple :

User-Agent: Awesome-Octocat-App

curl envoie par défaut un en-tête User-Agent valide. Si vous fournissez un en-tête User-Agent non valide avec curl (ou un autre client), vous recevez une réponse 403 Forbidden :

$ curl -IH 'User-Agent: ' https://api.github.com/meta
> HTTP/1.0 403 Forbidden
> Connection: close
> Content-Type: text/html

> Request forbidden by administrative rules.
> Please make sure your request has a User-Agent header.
> Check  for other possible causes.

Demandes conditionnelles

La plupart des réponses retournent un en-tête ETag. De nombreuses réponses renvoient également un en-tête Last-Modified. Vous pouvez utiliser les valeurs de ces en-têtes pour effectuer des demandes ultérieures à ces ressources à l’aide respectivement de l’en-tête If-None-Match et de l’en-tête If-Modified-Since. Si la ressource n’a pas changé, le serveur retourne 304 Not Modified.

Remarque : La création d’une demande conditionnelle et la réception d’une réponse 304 ne comptent pas par rapport à votre limite de débit. Nous vous encourageons donc à l’utiliser chaque fois que cela est possible.

$ curl -I https://api.github.com/user
> HTTP/2 200
> Cache-Control: private, max-age=60
> ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Vary: Accept, Authorization, Cookie
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4996
> x-ratelimit-reset: 1372700873

$ curl -I https://api.github.com/user -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
> HTTP/2 304
> Cache-Control: private, max-age=60
> ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Vary: Accept, Authorization, Cookie
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4996
> x-ratelimit-reset: 1372700873

$ curl -I https://api.github.com/user -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT"
> HTTP/2 304
> Cache-Control: private, max-age=60
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Vary: Accept, Authorization, Cookie
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4996
> x-ratelimit-reset: 1372700873

Partage des ressources cross-origin

L’API prend en charge le partage de ressources CORS (Cross-Origin Resource Sharing) pour les demandes AJAX de toute origine. Vous pouvez lire la recommandation CORS W3C ou cette introduction du guide de sécurité HTML 5.

Voici un exemple de demande envoyée par un navigateur qui atteint http://example.com :

$ curl -I https://api.github.com -H "Origin: http://example.com"
HTTP/2 302
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval

Voici à quoi ressemble la demande préliminaire CORS :

$ curl -I https://api.github.com -H "Origin: http://example.com" -X OPTIONS
HTTP/2 204
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-GitHub-OTP, X-Requested-With
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
Access-Control-Max-Age: 86400

Rappels JSON-P

Vous pouvez envoyer un paramètre ?callback à n’importe quel appel GET pour que les résultats s’encapsulent dans une fonction JSON. Cette technique est généralement utilisée lorsque les navigateurs doivent incorporer du contenu GitHub dans des pages web en contournant des problèmes interdomaines. La réponse inclut la même sortie de données que l’API classique, ainsi que les informations d’en-tête HTTP pertinentes.

$ curl https://api.github.com?callback=foo

> /**/foo({
>   "meta": {
>     "status": 200,
>     "x-ratelimit-limit": "5000",
>     "x-ratelimit-remaining": "4966",
>     "x-ratelimit-reset": "1372700873",
>     "Link": [ // pagination headers and other links
>       ["https://api.github.com?page=2", {"rel": "next"}]
>     ]
>   },
>   "data": {
>     // the data
>   }
> })

Vous pouvez écrire un gestionnaire JavaScript pour traiter le rappel. Voici un exemple minimal que vous pouvez essayer :

<html>
<head>
<script type="text/javascript">
function foo(response) {
  var meta = response.meta;
  var data = response.data;
  console.log(meta);
  console.log(data);
}

var script = document.createElement('script');
script.src = 'https://api.github.com?callback=foo';

document.getElementsByTagName('head')[0].appendChild(script);
</script>
</head>

<body>
  <p>Open up your browser's console.</p>
</body>
</html>

Tous les en-têtes possèdent la même valeur de chaîne que les en-têtes HTTP, à une exception notable : Link. Les en-têtes Link, préanalysés automatiquement, se présentent sous la forme d’un tableau de tuples [url, options].

Prenons l’exemple du lien suivant :

Link: <url1>; rel="next", <url2>; rel="foo"; bar="baz"

Il se présente ainsi dans la sortie de rappel :

{
  "Link": [
    [
      "url1",
      {
        "rel": "next"
      }
    ],
    [
      "url2",
      {
        "rel": "foo",
        "bar": "baz"
      }
    ]
  ]
}

Fuseaux horaires

Certaines demandes qui créent de nouvelles données (par exemple une validation) vous permettent de fournir des informations de fuseau horaire lorsque vous spécifiez ou générez des horodatages. Nous appliquons les règles suivantes, par ordre de priorité, pour déterminer les informations de fuseau horaire de ces appels d’API.

Notez que ces règles s’appliquent uniquement aux données transmises à l’API, et non aux données retournées par celle-ci. Comme il est mentionné dans « Schéma », les horodatages retournés par l’API sont au format UTC ISO 8601.

Indication explicite d’un horodatage ISO 8601 avec des informations de fuseau horaire

Dans le cas des appels d’API qui autorisent la spécification d’un horodatage, nous utilisons cet horodatage précis. L’API qui permet de gérer les commits en est un exemple. Pour plus d’informations, consultez « Commits ».

Ces horodatages se présentent ainsi : 2014-02-27T15:05:06+01:00. Pour savoir comment ces horodatages peuvent être spécifiés, consultez également cet exemple.

Utilisation de l’en-tête Time-Zone

Il est possible de fournir un en-tête Time-Zone qui définit un fuseau horaire en fonction de la liste des noms de la base de données Olson.

$ curl -H "Time-Zone: Europe/Amsterdam" -X POST https://api.github.com/repos/github/linguist/contents/new_file.md

Cela signifie qu’un horodatage est généré pour le moment où l’appel d’API est effectué dans le fuseau horaire défini par cet en-tête. Par exemple, l’API qui permet de gérer les contenus génère un commit Git pour chaque ajout ou modification, et utilise l’heure actuelle comme horodatage. Pour plus d’informations, consultez « Contenus ». Cet en-tête détermine le fuseau horaire utilisé pour générer cet horodatage actuel.

Utilisation du dernier fuseau horaire connu pour l’utilisateur

Si aucun en-tête Time-Zone n’est spécifié lorsque vous effectuez un appel authentifié à l’API, le fuseau horaire utilisé est le dernier fuseau connu de l’utilisateur authentifié. Il est mis à jour chaque fois que vous parcourez le site web GitHub.

Application de la valeur par défaut UTC sans autres informations de fuseau horaire

Si la procédure ci-dessus ne produit aucune information, c’est le fuseau horaire UTC qui est utilisé pour créer la validation Git.