Limites de Débit & Cache Redis
🚦 Niveaux d'accès
L'API n'a pas de clé : trois niveaux d'accès se distinguent par un secret partagé entre les serveurs de CLAIR (CLAIR_INTERNAL_SECRET, envoyé dans l'en-tête x-clair-internal), qui ne quitte jamais ces serveurs.
| Niveau | Qui | Limite |
|---|---|---|
| Anonyme | Tout appel direct à api.clair.vote : scripts, réutilisateurs, intégrations | 10 requêtes par minute et par IP |
| Navigateur relayé | Visiteur de clair.vote : ses appels passent par le proxy Next /api/v1/[...path], qui ajoute le secret et l'IP du visiteur (x-clair-client-ip) | 60 requêtes par minute et par IP de visiteur |
| Interne | Rendu serveur du site, sitemap, ingestion (secret, sans IP de visiteur) | Aucune |
Règles supplémentaires pour le niveau anonyme :
- User-Agent : les User-Agent
nodeetundiciexacts sont refusés (403). Identifiez votre client par un User-Agent descriptif, par exempleMonProjet/1.0 (contact@exemple.org). - Blocage temporaire : 30 réponses 429 en 5 minutes entraînent un blocage de l'IP pendant 1 heure.
Les routes /health sont exclues de la limitation. Pour un usage intensif de l'API : contact@clair.vote.
POST /api/v1/homepage/warm (invalidation du cache de la page d'accueil, appelée par l'ingestion en fin de batch) n'accepte que le niveau interne sans IP de visiteur : une requête relayée par le site reçoit un 403, comme toute requête sans le secret. La spécification OpenAPI déclare ce jeton (x-clair-internal) sur cette route ; il n'est pas délivré.
⚡ Cache Redis
Chaque route met sa réponse en cache avec une durée de vie propre :
| Module | Durée de vie |
|---|---|
| Page d'accueil | 27 h (bloc « à venir » : 15 min) |
| Parlementaires | 1 h, 12 h ou 24 h selon la route |
| Scrutins | 1 h (liste) ; 12 h (tags, scrutins importants) ; 24 h (années, périodes) |
| Dossiers | 1 h |
| Sujets | 1 h ; 12 h (sujets mis en avant, catégories) ; presse : 3 h, ou 15 min si le flux est vide |
| Groupes | 1 h ou 12 h selon la route |
| Commissions | 12 h ; 1 h pour ce qui dépend des réunions |
| Agenda | 1 h |
| Sénatoriales | 1 h ; résultats : 1 min |
| Lobbying, analytics | 12 h |
| Sitemap | 24 h |
Le batch nocturne ne reconstruit que la page d'accueil (voir Orchestrateur d'ingestion) ; les autres entrées expirent d'elles-mêmes. Après une correction massive de données, il faut purger les clés concernées dans Redis pour qu'elle soit visible immédiatement.
Au démarrage en production, l'API préchauffe une à une quelques routes : page d'accueil, premières pages de députés, de sénateurs et de scrutins, groupes des deux chambres, statistiques et secteurs du lobbying, première page des lobbyistes.