Meilleures pratiques pour utiliser l'API REST

Éviter l’interrogation

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 ».

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 mutatives

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.

La poursuite des demandes pendant que vous êtes limité peut entraîner l'interdiction de votre intégration.

Suivre les redirections

L’API REST GitHub 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 le dysfonctionnement 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 si nécessaire

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.

Par exemple, si une demande précédente a retourné la valeur 644b5b0155e6404a9cc4bd9d8b1ae730 pour l’en-tête etag, vous pouvez utiliser l’en-tête if-none-match dans une demande ultérieure :

curl -H "Authorization: Bearer YOUR-TOKEN" https://api.github.com/meta --include --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"'

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

curl -H "Authorization: Bearer YOUR-TOKEN" https://api.github.com/repos/github/docs --include --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT'

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.

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.

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