Référence API

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.

NiveauQuiLimite
AnonymeTout appel direct à api.clair.vote : scripts, réutilisateurs, intégrations10 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
InterneRendu serveur du site, sitemap, ingestion (secret, sans IP de visiteur)Aucune

Règles supplémentaires pour le niveau anonyme :

  • User-Agent : les User-Agent node et undici exacts sont refusés (403). Identifiez votre client par un User-Agent descriptif, par exemple MonProjet/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 :

ModuleDurée de vie
Page d'accueil27 h (bloc « à venir » : 15 min)
Parlementaires1 h, 12 h ou 24 h selon la route
Scrutins1 h (liste) ; 12 h (tags, scrutins importants) ; 24 h (années, périodes)
Dossiers1 h
Sujets1 h ; 12 h (sujets mis en avant, catégories) ; presse : 3 h, ou 15 min si le flux est vide
Groupes1 h ou 12 h selon la route
Commissions12 h ; 1 h pour ce qui dépend des réunions
Agenda1 h
Sénatoriales1 h ; résultats : 1 min
Lobbying, analytics12 h
Sitemap24 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.