Ressources disponibles dans l’API REST

schéma

L’API est accessible à partir de http(s)://HOSTNAME/api/v3. Toutes les données sont envoyées et reçues au format JSON.

$ curl -I http(s)://<em>HOSTNAME</em>/api/v3/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
> X-GitHub-Enterprise-Version: 3.6.0
> 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

GitHub vous recommande de créer un jeton pour vous authentifier auprès de l’API REST. Pour plus d’informations sur le type de jeton à créer, consultez « Authentification auprès de l’API REST ».

Vous pouvez authentifier votre requête en envoyant un jeton dans l’en-tête Authorization de votre requête :

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/octocat" \
--header "Authorization: Bearer YOUR-TOKEN"

Si vous essayez d’utiliser un point de terminaison de l’API REST sans jeton ou avec un jeton disposant d’autorisations insuffisantes, vous recevez une réponse 404 Not Found ou 403 Forbidden.

Clé/secret OAuth2

curl -u my_client_id:my_client_secret 'http(s)://<em>HOSTNAME</em>/api/v3/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 OAuth app 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. Ne divulguez pas le secret client de vos OAuth app à vos utilisateurs.

Vous ne pourrez pas vous authentifier à l’aide de votre clé OAuth2 et de votre secret en mode privé. Toute tentative d’authentification retournera 401 Unauthorized. Pour plus d’informations, consultez « Activation du mode privé ».

Limite d’échecs de connexion

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

$ curl -I http(s)://<em>HOSTNAME</em>/api/v3 --header "Authorization: Bearer INVALID-TOKEN"
> HTTP/2 401

> {
>   "message": "Bad credentials",
>   "documentation_url": "https://docs.github.com/enterprise/3.6/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 :

> HTTP/2 403
> {
>   "message": "Maximum number of login attempts exceeded. Please try again later.",
>   "documentation_url": "https://docs.github.com/enterprise/3.6/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 "http(s)://<em>HOSTNAME</em>/api/v3/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 --header "Authorization: Bearer YOUR-TOKEN" -d '{"scopes":["repo_deployment"]}' http(s)://<em>HOSTNAME</em>/api/v3/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:PASSWORD http(s)://<em>HOSTNAME</em>/api/v3

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

Code d'erreur	Description
missing	Une ressource n’existe pas.
missing_field	Un champ obligatoire sur une ressource n’a pas été défini.
invalid	La mise en forme d’un champ n’est pas valide. Pour plus d’informations, consultez la documentation.
already_exists	Une 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).
unprocessable	Les 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 Enterprise Server 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.

Un code d’état 301 indique une redirection 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.

Un code d’état 302 ou 307 indique une redirection 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 Enterprise Server s’efforce d’utiliser les verbes HTTP appropriés pour chaque action. Notez que les verbes HTTP respectent la casse.

Verbe	Description
HEAD	Peut être émis sur n’importe quelle ressource pour obtenir uniquement les informations d’en-tête HTTP.
GET	Utilisé pour récupérer des ressources.
POST	Utilisé pour créer des ressources.
PATCH	Utilisé 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.
PUT	Utilisé 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.
DELETE	Utilisé 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 Enterprise Server 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 REST GitHub Enterprise Server 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 à votre instance GitHub Enterprise Server. En outre, les points de terminaison de recherche ont des limites dédiées. Pour plus d’informations, consultez « Rechercher » dans la documentation de l’API REST.

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

Vous pouvez effectuer des demandes d’API directes que vous authentifiez avec un personal access token. Une OAuth app ou une GitHub App peut également effectuer une demande en votre nom une fois que vous avez autorisé l’application. Pour plus d’informations, consultez « Gestion de vos jetons d’accès personnels », « Autorisation des applications OAuth » et « Autorisation des applications GitHub ».

GitHub Enterprise Server associe toutes ces demandes avec l’utilisateur authentifié. Pour les OAuth apps et les GitHub Apps, c’est l’utilisateur qui a autorisé l’application. Toutes ces demandes sont comptabilisées par rapport à la limite de débit de l’utilisateur authentifié.

Par défaut, les requêtes jeton d’accès utilisateur sont limitées à 5 000 requêtes par heure et par utilisateur authentifié. Toutes les demandes provenant de OAuth apps autorisées par un utilisateur ou d'un personal access token appartenant à l'utilisateur, et les demandes authentifiées avec n'importe quel identifiant d'authentification de l'utilisateur, partagent le même quota de demandes par heure pour l'utilisateur en question.

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

Les demandes provenant d’une GitHub App peuvent utiliser un jeton d’accès utilisateur ou un jeton d’accès d’installation. Pour plus d’informations sur les limites de débit des GitHub Apps, consultez « Limites de débit pour les 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 par jeton automatique ».

Avec GITHUB_TOKEN, la limite de débit s’élève à 1 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 http(s)://<em>HOSTNAME</em>/api/v3/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ête	Description
x-ratelimit-limit	Nombre maximal de demandes autorisées par heure.
x-ratelimit-remaining	Nombre de demandes restantes dans la fenêtre de limite de débit actuelle.
x-ratelimit-used	Nombre de demandes que vous avez faites dans la fenêtre de limite de débit actuelle.
x-ratelimit-reset	Heure à 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 du taux ». 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/enterprise/3.6/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ée pour les OAuth apps

Si votre OAuth app doit effectuer des appels non authentifiés à des ressources publiques avec une limite de débit plus élevée, vous pouvez passer l’ID client et le secret de votre application avant la route du point de terminaison.

$ curl -u my_client_id:my_client_secret -I http(s)://<em>HOSTNAME</em>/api/v3/meta
> 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

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 Enterprise Server, 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/enterprise/3.6/rest/overview/resources-in-the-rest-api#secondary-rate-limits"
> }

Vous devez attendre et essayer votre requête ultérieurement. 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é. Si l’en-tête x-ratelimit-remaining est 0, 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). Dans le cas contraire, attendez une augmentation exponentielle du temps entre les nouvelles tentatives et levez une erreur après un nombre spécifique de nouvelles tentatives.

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.

$ curl -I http(s)://<em>HOSTNAME</em>/api/v3/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 http(s)://<em>HOSTNAME</em>/api/v3/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 http(s)://<em>HOSTNAME</em>/api/v3/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 http(s)://<em>HOSTNAME</em>/api/v3 -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 http(s)://<em>HOSTNAME</em>/api/v3 -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 Enterprise Server 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 http(s)://<em>HOSTNAME</em>/api/v3?callback=foo

> /**/foo({
>   "meta": {
>     "status": 200,
>     "x-ratelimit-limit": "5000",
>     "x-ratelimit-remaining": "4966",
>     "x-ratelimit-reset": "1372700873",
>     "Link": [ // pagination headers and other links
>       ["http(s)://<em>HOSTNAME</em>/api/v3?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 = 'http(s)://HOSTNAME/api/v3?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.

• Indication explicite d’un horodatage ISO 8601 avec des informations de fuseau horaire
• Utilisation de l’en-tête Time-Zone
• Utilisation du dernier fuseau horaire connu pour l’utilisateur
• Application de la valeur par défaut UTC sans autres informations de fuseau horaire

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 « Base de données Git ».

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 http(s)://<em>HOSTNAME</em>/api/v3/repos/github-linguist/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 « Référentiels ». 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 Enterprise Server.

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.