limier/docs/07-api.md

API

Documentation interactive : https://limier.tips-of-mine.com/api/docs. Schéma OpenAPI : /api/openapi.json.

Authentification par cookie de session HttpOnly, posé par le parcours OIDC. Aucun jeton n'est accessible au JavaScript.

Routes

Exploitation

Méthode	Chemin	Auth	Rôle
GET	/api/sante	non	sonde du healthcheck, triviale
GET	/api/pret	non	vérifie PostgreSQL, Redis, base sites
GET	/api/metriques	non	compteurs Prometheus
GET	/api/catalogue	non	types, sites, modules actifs

Authentification

Méthode	Chemin	Rôle
GET	/api/auth/connexion	redirige vers Authentik (PKCE)
GET	/api/auth/retour	rappel OIDC
POST	/api/auth/deconnexion	ferme la session
GET	/api/auth/moi	état du compte et quota

Recherches

Méthode	Chemin	Auth	Rôle
POST	/api/recherches	oui	lance une recherche
POST	/api/recherches/variantes	non	aperçu des variantes
GET	/api/recherches	oui	historique
GET	/api/recherches/statistiques/mensuelles	oui	répartition par type
GET	/api/recherches/{id}	oui	détail et résultats
GET	/api/recherches/{id}/flux	oui	progression en direct (SSE)
DELETE	/api/recherches/{id}	oui	suppression

/statistiques/mensuelles est déclarée avant /{recherche_id} : FastAPI teste les routes dans l'ordre de déclaration, et « statistiques » serait sinon lu comme un UUID. Un test couvre cette non-régression.

Confidentialité

Méthode	Chemin	Auth	Rôle
GET	/api/confidentialite	non	politique appliquée
POST	/api/confidentialite/effacement	non	demande d'effacement
GET	/api/confidentialite/export	oui	export complet (art. 20)

Administration — groupe GL-Limier-Admin

/api/admin/tableau-de-bord, /sites, /sites/auto-controle, /proxies, /modules, /effacements, /effacements/{id}/appliquer, /purge, /utilisateurs, /utilisateurs/{id}/plan, /utilisateurs/{id}/blocage.

Un administrateur ne lit pas les recherches des autres : ce serait contredire la politique de minimisation annoncée aux visiteurs.

Lancer une recherche

curl -X POST https://limier.tips-of-mine.com/api/recherches \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"kind":"name","term":"Hubert Cornet","deep":false}'

kind : username, name, email, domain.

Réponse 202 avec l'identifiant. S'abonner ensuite au flux.

Le flux SSE

const source = new EventSource(`/api/recherches/${id}/flux`, { withCredentials: true });
source.onmessage = (m) => {
  const e = JSON.parse(m.data);   // debut | progress | finding | notice | fin
  if (e.type === "fin") source.close();
};

Les évènements déjà émis sont rejoués à la connexion : arriver en retard ou se reconnecter ne fait rien perdre. EventSource renvoie Last-Event-ID, le backend ne rejoue que le manquant. Un battement (: ping) toutes les 20 s empêche le tunnel Cloudflare de fermer une connexion silencieuse.

Codes de refus

HTTP	X-Limier-Code	Sens
401	authentification_requise	connexion nécessaire
402	quota_depasse	quota mensuel épuisé
403	droits_insuffisants	réservé aux administrateurs
422	requete_invalide	terme mal formé
429	debit_depasse	limite horaire atteinte
451	identifiant_bloque	effacement appliqué sur cet identifiant
503	moteur_indisponible	moteur désactivé sur l'instance