Testez la façon dont votre application gère les limites de débit d’API GitHub

En un clin d’œil
Objectif : Testez la façon dont votre application gère les limites de débit d’API REST GitHub
Heure : 15 minutes
Plugins :RateLimitingPlugin, GenericRandomErrorPlugin, RetryAfterPlugin
Prérequis :configurer le proxy de développement

Votre application appelle l’API GitHub. Votre application fonctionne sur votre machine, puis une tâche CI, une grande organisation ou une journée de forte activité lui fait dépasser la limite de débit, et elle commence à échouer. Pour le tester sur l’API réelle, vous devrez épuiser votre limite de requêtes, puis attendre jusqu’à une heure avant de pouvoir réessayer. Dev Proxy simule localement les limites de débit de GitHub, avec une limite et une fenêtre de temps que vous choisissez.

Savoir ce que GitHub retourne

GitHub applique deux types de limites de débit pour l'API REST.

Les limites de débit principales plafonnent le nombre de requêtes que vous pouvez effectuer par heure. Par exemple, 60 pour les requêtes non authentifiées et 5 000 pour les requêtes avec un jeton d’accès personnel. Chaque réponse inclut des en-têtes qui indiquent où vous êtes :

Lorsque vous dépassez la limite principale, GitHub retourne 403 ou 429 avec x-ratelimit-remaining défini sur 0. Ne réessayez pas tant que l’heure indiquée dans x-ratelimit-reset n’est pas atteinte.

Les limites de taux secondaires protègent GitHub contre les pics d’activité, comme un trop grand nombre de requêtes simultanées ou la création de trop de contenu trop rapidement. Lorsque vous dépassez une limite secondaire, GitHub renvoie 403 ou 429 avec un message indiquant qu'une limite de débit secondaire a été atteinte. Si la réponse a un en-tête retry-after, attendez ce nombre de secondes. Sinon, attendez au moins une minute et augmentez le temps d’attente si la requête échoue.

GitHub peut bannir les intégrations qui continuent d'envoyer des requêtes alors qu'elles sont soumises à une limitation de débit. Pour plus d’informations, consultez Les limites de débit pour l’API REST dans la documentation GitHub.

Simuler la limite de débit principale

Utilisez RateLimitingPlugin pour compter les requêtes et retourner les en-têtes de limite de débit de GitHub. Pour tester sans attendre une heure, utilisez une petite limite et une courte fenêtre.

Fichier : devproxyrc.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/rc.schema.json",
  "plugins": [
    {
      "name": "RetryAfterPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
    },
    {
      "name": "RateLimitingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
      "configSection": "githubRateLimit"
    }
  ],
  "urlsToWatch": [
    "https://api.github.com/*"
  ],
  "githubRateLimit": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/ratelimitingplugin.schema.json",
    "headerLimit": "x-ratelimit-limit",
    "headerRemaining": "x-ratelimit-remaining",
    "headerReset": "x-ratelimit-reset",
    "resetFormat": "UtcEpochSeconds",
    "costPerRequest": 1,
    "rateLimit": 5,
    "resetTimeWindowSeconds": 60,
    "warningThresholdPercent": 0,
    "whenLimitExceeded": "Custom",
    "customResponseFile": "github-rate-limit-exceeded.json"
  }
}

Dans le fichier de réponse personnalisé, définissez la réponse que GitHub retourne lorsque vous dépassez la limite de débit primaire.

Fichier : github-rate-limit-exceeded.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/ratelimitingplugin.customresponsefile.schema.json",
  "statusCode": 429,
  "headers": [
    {
      "name": "content-type",
      "value": "application/json; charset=utf-8"
    }
  ],
  "body": {
    "message": "API rate limit exceeded for user ID 1.",
    "documentation_url": "https://docs.github.com/rest/overview/rate-limits-for-the-rest-api"
  }
}

Démarrez le proxy de développement et exécutez votre application.

devproxy --config-file devproxyrc.json

Dev Proxy transmet les cinq premières requêtes de chaque minute à GitHub et définit les en-têtes x-ratelimit-* dans les réponses. À partir de la sixième requête, Dev Proxy renvoie la réponse de limitation de débit avec x-ratelimit-remaining défini sur 0 et x-ratelimit-reset défini sur la fin de la fenêtre. Si votre application appelle à nouveau l'API avant la réinitialisation de la fenêtre, RetryAfterPlugin le signale et limite le débit de la requête.

Vérifiez que votre application :

• Lit x-ratelimit-remaining et ralentit avant d’atteindre 0.
• Cesse d'appeler l'API après une réponse de limitation de débit et attend jusqu'à x-ratelimit-reset.
• Informe l'utilisateur de ce qui se passe, par exemple « Limite de débit GitHub atteinte, nouvelle tentative à 14 h 05 », au lieu d'échouer silencieusement.

Simuler des limites de taux secondaires

Les limites de débit secondaires se déclenchent lors de pics de requêtes et incluent un en-tête retry-after. Utilisez GenericRandomErrorPlugin pour les retourner au hasard.

Fichier : devproxyrc.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/rc.schema.json",
  "plugins": [
    {
      "name": "RetryAfterPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
    },
    {
      "name": "GenericRandomErrorPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
      "configSection": "githubSecondaryRateLimit"
    }
  ],
  "urlsToWatch": [
    "https://api.github.com/*"
  ],
  "githubSecondaryRateLimit": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/genericrandomerrorplugin.schema.json",
    "errorsFile": "github-secondary-rate-limit.json",
    "rate": 50,
    "retryAfterInSeconds": 60
  }
}

Fichier : github-secondary-rate-limit.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/genericrandomerrorplugin.errorsfile.schema.json",
  "errors": [
    {
      "request": {
        "url": "https://api.github.com/*"
      },
      "responses": [
        {
          "statusCode": 429,
          "headers": [
            {
              "name": "content-type",
              "value": "application/json; charset=utf-8"
            },
            {
              "name": "retry-after",
              "value": "@dynamic"
            }
          ],
          "body": {
            "message": "You have exceeded a secondary rate limit. Please wait a few minutes before you try again.",
            "documentation_url": "https://docs.github.com/rest/overview/rate-limits-for-the-rest-api#about-secondary-rate-limits"
          }
        }
      ]
    }
  ]
}

Démarrez le proxy de développement et exécutez votre application. Vérifiez que votre application attend le nombre de secondes indiqué dans l’en-tête retry-after avant d’appeler à nouveau l’API. Si ce n’est pas le cas, le RetryAfterPlugin le signale.

Si vous utilisez Octokit avec le plugin de limitation du débit, vérifiez que vos gestionnaires onSecondaryRateLimit et onRateLimit s’exécutent et qu’ils renvoient le résultat attendu.

Étape suivante

Découvrez plus en détail l’RateLimitingPlugin.

Voir aussi

• Simuler des réponses d'API de limitation de débit – Limites de débit sur n'importe quelle API
• Vérifier que mon application gère correctement la limitation du débit - Limitation du débit sur n’importe quelle API
• RetryAfterPlugin - Vérifier le comportement de nouvelle tentative
• Utiliser le proxy de développement dans CI/CD - Automatiser les tests de résilience dans votre pipeline