Contexte
Les API (Interfaces de Programmation Applicative) permettent aux applications tierces d’accéder à des données et services de manière standardisée.
Pour garantir la sécurité, la disponibilité et la qualité de service, il est indispensable de mettre en place deux mécanismes :
l’authentification des appels API.
la limitation du nombre de requêtes (rate limiting).
Nos API sont accessibles à tout utilisateur authentifié (voir documentation) et permettent, selon le niveau de droits, d'accéder directement à différentes ressources liées à leur compte (nœuds, agents, configurations, etc.), ou de déclencher des actions.
Le concept de limitation (Rate Limiting)
Le rate limiting consiste à restreindre le nombre de requêtes qu’un client peut effectuer sur une période donnée. L’objectif est d’assurer la stabilité du service et d’éviter les abus (surcharge, déni de service, usage non maîtrisé).
Pourquoi limiter les appels ?
Protéger l’infrastructure contre une charge excessive.
Garantir une répartition équitable des ressources entre les utilisateurs.
Prévenir les usages malveillants (bots, attaques par force brute).
Règles de limitation
Les limitations en vigueur concernent principalement 2 facteurs identifiants.
À noter : les 2 modes de limitation agissent simultanément, tout blocage éventuel émanant alors du premier des modes ayant atteint sa limite.
Clé d'API (api_key)
À l'échelle d'un compte applicatif, cette clé peut être partagée par plusieurs utilisateurs, dont les jetons d'API dérivent de celle-ci.
Nombre maximum de requêtes : 10
Délai de régénération : 10 requêtes par seconde
Jeton d'API (api_token)
A l'échelle d'un utilisateur, ce jeton, lié à une clé d'API commune, est personnel.
À noter : plusieurs jetons d'API liés à un même utilisateur (identifié par son adresse email) utilisés en parallèle ne permettent pas d'étendre la limite, et sont comptabilisés comme une source unique.
Nombre maximum de requêtes : 20
Délai de régénération : 1 requête par seconde
Bonnes pratiques pour les consommateurs de l’API
Mettre en cache les réponses pour réduire les appels inutiles.
Implémenter une logique de nouvelles tentatives avec délais progressifs en cas d’erreur 429.
Surveiller sa consommation pour rester dans les limites autorisées
En-têtes de réponses
Les réponses d'API exposeront, parmi les informations d'en-tête, plusieurs clés utiles à la gestion d'erreur :
- X-RateLimit-Remaining : nombre de requêtes qu'il est encore possible d'émettre avant blocage.
X-RateLimit-Retry-After : nombre de secondes avant de pouvoir émettre à nouveau une requête (0 tant qu'aucun blocage n'est atteint).
X-RateLimit-Limit : nombre maximum de requêtes concurrentes qu'il est possible d'émettre.
-
X-RateLimit-From : règle à l'origine de la limitation, parmi :
api_key / api_token : règles principales détaillées dans la partie Règles de limitation
ip / user_id : limitations spécifiques à la prise de main à distance