Meilleures pratiques pour utiliser l'API REST

Éviter le sondage

Vous devez vous abonner aux événements de webhook au lieu d’interroger l’API pour rechercher des données. Ce qui aidera votre intégration à rester dans la limite de débit d’API. Pour plus d’informations, consultez « Documentation sur les webhooks ».

Si vous ne pouvez pas utiliser de webhooks et que vous devez interroger l’API, interrogez aussi efficacement que possible pour éviter de dépasser la limite de débit :

• Interrogez seulement aussi souvent que nécessaire, selon une planification fixe. Si une réponse inclut un x-poll-interval en-tête, attendez au moins ce nombre de secondes avant d’interroger à nouveau le même point de terminaison.
• Effectuez des requêtes conditionnelles authentifiées afin que les données inchangées ne soient pas comptabilisées par rapport à votre limite de taux principal. Pour plus d’informations, consultez Utiliser des demandes conditionnelles.
• Demandez uniquement les données dont vous avez besoin, et veillez à ce que les réponses restent stables, afin qu’un plus grand nombre de vos interrogations renvoient 304 Not Modified. Pour plus d’informations, consultez Effectuer des demandes pouvant être mises en cache.

Formuler des demandes authentifiées

Les demandes authentifiées ont une limitation de débit primaire plus élevée que celles qui ne le sont pas. Pour éviter de dépasser la limitation de débit, il est donc recommandé de formuler des demandes authentifiées. Pour plus d’informations, consultez « Limites de débit pour l'API REST ».

Éviter les demandes simultanées

Pour éviter de dépasser les limitations de débit secondaires, vous devez formuler des demandes en série plutôt que simultanément. Pour ce faire, vous pouvez implémenter un système de file d’attente pour les demandes.

Pause entre les demandes de changement

Si vous formulez un grand nombre de demandes POST, PATCH, PUT ou DELETE, attendez au moins une seconde entre chaque demande. Cela vous aidera à rester en dessous des limitations de débit secondaires.

Gérer les erreurs de limitation de débit de manière appropriée

Si vous recevez une erreur de limite de débit, vous devez arrêter temporairement d’effectuer des demandes en fonction des instructions suivantes :

• 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 effectuer une autre demande avant la durée spécifiée par l’en-tête x-ratelimit-reset. L’en-tête x-ratelimit-reset est en secondes d’époque UTC.
• Sinon, attendez au moins une minute avant de réessayer. Si votre demande continue d'échouer en raison d'une limite de débit secondaire, attendez une durée exponentiellement croissante entre les nouvelles tentatives et levez une erreur après un nombre spécifique de nouvelles tentatives.

Continuer à effectuer des requêtes alors que vous êtes limité par le rate limit peut entraîner le bannissement de votre intégration.

Suivre les redirections

L’API GitHub REST utilise la redirection HTTP le cas échéant. Vous devez partir du principe que toute demande peut entraîner une redirection. La réception d’une redirection HTTP ne constitue pas une erreur, et vous devez suivre cette redirection.

Un code d’état 301 indique une redirection permanente. Vous devez répéter votre demande à l’URL spécifiée par l’en-tête location. En outre, vous devez mettre à jour votre code pour utiliser cette URL pour les demandes ultérieures.

Un code d’état 302 ou 307 indique une redirection temporaire. Vous devez répéter votre demande à l’URL spécifiée par l’en-tête location. Toutefois, vous ne devez pas mettre à jour votre code pour utiliser cette URL pour les demandes ultérieures.

D’autres codes d’état de redirection peuvent être utilisés conformément aux spécifications HTTP.

Ne pas analyser manuellement les URL

De nombreux points de terminaison d’API retournent des valeurs d’URL pour les champs dans le corps de la réponse. Il est déconseillé d’essayer d’analyser ces URL ou de prévoir la structure des URL futures. Cela peut entraîner l’arrêt de votre intégration si GitHub modifie la structure de l’URL à l’avenir. Au lieu de cela, il est recommandé de rechercher un champ qui contient les informations dont vous avez besoin. Par exemple, le point de terminaison utilisé pour créer un problème retourne un champ html_url avec une valeur de type https://github.com/octocat/Hello-World/issues/1347 et un champ number avec une valeur de type 1347. Si vous avez besoin de connaître le numéro du problème, utilisez le champ number au lieu d’analyser le champ html_url.

De même, il est déconseillé d’essayer de construire manuellement des requêtes de pagination. Au lieu de cela, utilisez les en-têtes de lien pour déterminer quelles pages de résultats peuvent faire l’objet d’une demande. Pour plus d’informations, consultez « Utilisation de la pagination dans l’API REST ».

Utiliser des demandes conditionnelles

La plupart des points de terminaison retournent un en-tête etag et ils sont nombreux à retourner un en-tête last-modified. Vous pouvez utiliser les valeurs de ces en-têtes pour formuler des demandes conditionnelles GET. Si la réponse n’a pas changé, vous recevrez une réponse 304 Not Modified. L’établissement d’une requête conditionnelle n’est pas pris en compte dans votre limite de débit principale si une réponse 304 est renvoyée et que la requête a été effectuée avec une autorisation correcte à l’aide d’un en-tête Authorization. Cela rend les requêtes conditionnelles particulièrement utiles lorsque vous interrogez un point de terminaison, car chaque 304 Not Modified réponse est rapide et n’utilise pas votre limite de débit.

Dans les exemples suivants, remplacez YOUR-TOKEN par votre jeton d’accès. Remplacez REPO-OWNER par le compte propriétaire du référentiel, puis remplacez REPO-NAME par le nom du référentiel.

Pour effectuer une requête conditionnelle avec un etag:

1. Effectuez une requête et enregistrez la valeur de l’en-tête etag de la réponse.

   curl --include --header "Authorization: Bearer YOUR-TOKEN" http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/pulls
   

   La réponse inclut un etag en-tête :

   HTTP/2 200
   etag: "644b5b0155e6404a9cc4bd9d8b1ae730"
   

2. Dans votre requête suivante vers la même URL, envoyez la valeur enregistrée dans l’en-tête if-none-match .

   curl --include --header "Authorization: Bearer YOUR-TOKEN" --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"' http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/pulls
   

   Si les données n’ont pas changé, vous recevrez une 304 Not Modified réponse, qui ne compte pas sur votre limite de taux primaire :

   HTTP/2 304
   

Vous pouvez également utiliser l’en-tête last-modified . Par exemple, si une demande précédente a retourné la valeur last-modified pour l’en-tête Wed, 25 Oct 2023 19:17:59 GMT, vous pouvez utiliser l’en-tête if-modified-since dans une demande ultérieure :

curl --include --header "Authorization: Bearer YOUR-TOKEN" --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT' http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME

Les demandes conditionnelles pour les méthodes non sécurisées, telles que POST, PUT, PATCH et DELETE ne sont pas prises en charge, sauf indication contraire dans la documentation d’un point de terminaison spécifique.

Effectuer des demandes pouvant être mises en cache

Une demande conditionnelle vous permet uniquement de gagner du temps et de limiter le débit si le point de terminaison retourne 304 Not Modified. Le point de terminaison retourne 304 lorsque la représentation que vous avez demandée n’a pas changé depuis que vous avez enregistré sa valeur etag ou last-modified ; les en-têtes de réponse non liés, tels que la date, peuvent toujours différer. Pour augmenter les chances d’obtenir des réponses 304 lors de vos sondages, gardez vos requêtes stables et spécifiques.

Demandez uniquement les données dont vous avez besoin. Une réponse plus petite et plus spécifique change moins souvent, de sorte qu’elle retourne 304 Not Modified plus souvent. Par exemple, pour vérifier les demandes de tirage pour une branche, filtrez la liste par cette branche au lieu de répertorier chaque demande de tirage et de rechercher vous-même les résultats. Remplacez HEAD-OWNER par le compte auquel appartient la branche source ; pour une pull request provenant d’un fork, il s’agit du compte auquel appartient le fork. Remplacez BRANCH-NAME par le nom de la branche et encodez-l’URL s’il contient des caractères spéciaux tels que # ou &:

curl --include --header "Authorization: Bearer YOUR-TOKEN" "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/pulls?head=HEAD-OWNER:BRANCH-NAME"

Si vous parcourez une liste, utilisez un ordre de tri stable. Certains paramètres, tels que sort=updated, réorganisez la liste chaque fois qu’un élément change. Lorsqu’un élément passe à une nouvelle position, les éléments entre ses anciennes et nouvelles positions se déplacent sur différentes pages, de sorte que les pages que vous avez déjà extraites peuvent retourner de nouvelles données au lieu de 304 Not Modified. Un ordre stable, tel que la valeur par défaut, empêche les mises à jour des éléments existants de réorganiser la liste, même si l’ajout ou la suppression d’éléments peut toujours déplacer des entrées sur d’autres pages.

Utilisez les mêmes paramètres chaque fois que vous interrogez les mêmes données. Une autre taille de page, numéro de page ou filtre produit une réponse différente avec un autre etag.

Ne pas ignorer les erreurs

Il est déconseillé d’ignorer les codes d’erreur 4xx et 5xx qui reviennent plusieurs fois. Au lieu de cela, vérifiez que vous interagissez correctement avec l’API. Par exemple, si un point de terminaison demande une chaîne et que vous transmettez une valeur numérique, vous recevrez une erreur de validation. De même, toute tentative d’accès à un point de terminaison non autorisé ou inexistant entraîne une erreur 4xx.

Si vous interrogez et qu’une ressource retourne à plusieurs reprises une 404 Not Found réponse, ne continuez pas à la demander sur chaque sondage. Tout d’abord, assurez-vous que 404 n’est pas causé par l’authentification ou l’autorisation. GitHub retourne une 404 Not Found réponse au lieu d’une 403 Forbidden réponse pour certaines ressources privées lorsque vos informations d’identification n’accordent pas l’accès, ce qui 404 signifie que la ressource n’est pas toujours absente. Pour plus d’informations, consultez « Résolution des problèmes de l’API REST ». Une fois que vous avez confirmé que vos informations d’identification sont correctes, attendez beaucoup plus longtemps avant de vérifier à nouveau, ou vérifiez à nouveau uniquement lorsque vous avez une raison de croire que la ressource existe maintenant. Demander à plusieurs reprises une ressource manquante gaspille votre limite de débit et peut déclencher une limite de débit secondaire.

Le fait d’ignorer intentionnellement toutes les erreurs de validation peut entraîner la suspension de votre application pour abus.

Pour aller plus loin

• Meilleures pratiques en matière d’utilisation des webhooks
• Meilleures pratiques pour la création d’une application GitHub