Ressources disponibles dans l’API REST

schéma

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

$ curl -I https://<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: GitHub AE
> 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 "https://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.

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

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

> {
>   "message": "Bad credentials",
>   "documentation_url": "https://docs.github.com/github-ae@latest/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/github-ae@latest/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://<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"]}' https://<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:TOKEN https://<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 ».

Verbes HTTP

Dans la mesure du possible, l’API REST GitHub AE 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"

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://<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 https://<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 AE 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://<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
>       ["https://<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 = 'https://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 https://<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 AE.

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.

Ressources disponibles dans l’API REST

Dans cet article