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

Suivre les redirections que l’API envoie

GitHub est explicite lorsqu’il indique à quel moment une ressource a été déplacée. Pour cela, il fournit un code d’état de redirection. Vous devez suivre ces redirections. Chaque réponse de redirection définit l’en-tête Location avec le nouvel URI auquel accéder. Si vous recevez une redirection, il est préférable de mettre à jour votre code pour suivre le nouvel URI, dans le cas où vous demanderiez un chemin déprécié susceptible d’être supprimé.

Nous avons fourni la liste des codes d’état HTTP à surveiller lorsque vous concevez votre application en vue de suivre les redirections.

N’analysez pas manuellement les URL

Souvent, les réponses d’API contiennent des données sous la forme d’URL. Par exemple, lors d’une demande de dépôt, nous allons envoyer une clé appelée clone_url avec une URL que vous pourrez utiliser pour cloner le dépôt.

Pour la stabilité de votre application, vous ne devez pas essayer d’analyser ces données, ni de deviner et de construire le format des futures URL. Votre application sera susceptible de ne plus fonctionner si nous décidons de modifier l’URL.

Par exemple, lors d’une utilisation de résultats paginés, il est souvent tentant de construire des URL avec ?page=<number> à la fin. Ne cédez pas à cette tentation. Pour plus d’informations sur le suivi fiable des résultats paginés, consultez « Utilisation de la pagination dans l’API REST ».

Gestion des limites de débit

La limite de débit de l’API GitHub garantit que l’API est rapide et disponible pour tout le monde.

Si vous atteignez une limite de débit, vous devez arrêter de faire des demandes jusqu’à l’heure spécifiée par l’en-tête x-ratelimit-reset. Si vous ne le faites pas, votre intégration risque d’être interdite. Pour plus d’informations, consultez « Ressources disponibles dans l’API REST ».

Gestion des limites de débit secondaires

GitHub peut également utiliser des limites de débit secondaires pour garantir la disponibilité de l’API. Pour plus d’informations, consultez « Ressources disponibles dans l’API REST ».

Pour éviter d’atteindre cette limite, vous devez vous assurer que votre application respecte les instructions ci-dessous.

Effectuez des demandes authentifiées ou utilisez l’ID client et le secret de votre application. Les demandes non authentifiées sont soumises à une limitation de débit secondaire plus agressive.
Effectuez des demandes pour un seul utilisateur ou ID client de façon séquentielle. Vous ne devez pas effectuer de demandes pour un seul utilisateur ou un seul ID client de façon simultanée.
Si vous effectuez un grand nombre de demandes POST, PATCH, PUT ou DELETE pour un utilisateur ou ID client unique, attendez au moins une seconde entre chaque demande.
Lorsque vous avez été limité, attendez avant de retenter votre demande.
- Si l’en-tête de réponse Retry-After est présent, retentez votre demande après l’heure spécifiée dans l’en-tête. La valeur de l’en-tête Retry-After est toujours un entier correspondant au nombre de secondes que vous devez attendre avant d’effectuer à nouveau des demandes. Par exemple, Retry-After: 30 signifie que vous devez attendre 30 secondes avant d’envoyer d’autres demandes.
- Si l’en-tête x-ratelimit-remaining est 0, retentez votre demande après l’heure spécifiée par l’en-tête x-ratelimit-reset. L’en-tête x-ratelimit-reset est toujours un entier représentant l’heure à laquelle la fenêtre de limite de débit actuelle est réinitialisée en secondes d’époque 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.

GitHub se réserve le droit de modifier ces instructions si nécessaire pour garantir la disponibilité.

Gestion des erreurs d’API

Même si votre code ne peut pas générer de bogue, vous pouvez rencontrer des erreurs successives lorsque vous tentez d’accéder à l’API.

Au lieu d’ignorer les codes d’état 4xx et 5xx, 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 5xx et votre appel échouera. 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.