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"
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
.
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
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. Pour plus d’informations, notamment sur les baisses de tension planifiées, consultez le billet de blog.
L’authentification auprès de l’API à l’aide des paramètres de requête, bien que disponible, n’est plus prise en charge pour des raisons de sécurité. Nous recommandons plutôt aux intégrateurs de déplacer leur jeton d’accès, client_id
ou client_secret
dans l’en-tête. GitHub publiera un préavis pour annoncer la suppression de l’authentification au moyen des paramètres de requête.
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 :
-
L’envoi de JSON non valide entraîne une réponse
400 Bad Request
.HTTP/2 400 Content-Length: 35 {"message":"Problems parsing JSON"}
-
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"}
-
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.
Les limites de débit sont désactivées par défaut pour GitHub Enterprise Server. Contactez l’administrateur de votre site afin de confirmer les limites de débit pour votre instance.
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
Remarque : Ne partagez jamais votre secret client avec quiconque. Ne l’incluez pas dans le code du navigateur côté client.
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.