API publique Scolariis

Authentification

Chaque appel est authentifié par une clé, jamais par un cookie de session. Une clé se crée depuis /parametres/api, par l'administrateur ou le directeur de l'établissement — c'est un geste de configuration, pas une consultation.

Une clé ne porte que les droits (« scopes ») qui lui ont été accordés à sa création, et jamais plus que les droits du rôle qui l'a créée.

Forme d'un appel

La clé se transmet dans l'en-tête Authorization, au format porteur (« Bearer »). Jamais dans l'URL : une clé passée en paramètre de requête finirait en clair dans des journaux qui ne lui sont pas destinés.

GET /api/v1/eleves?page=1&par_page=25 HTTP/1.1
Host: votre-domaine.tld
Authorization: Bearer sk_live_<prefixe>_<secret>

Enveloppe de réponse et pagination

Une liste répond avec ses données et un bloc de pagination ; un élément unique ne répond qu'avec ses données.

{
  "donnees": [ { "id": 1, "...": "..." } ],
  "pagination": { "page": 1, "par_page": 25, "total": 138 }
}

Deux paramètres de requête pilotent la pagination sur les listes :

• page — le numéro de page, à partir de 1.
• par_page — le nombre de résultats par page ; 25 par défaut, 100 au maximum.

Codes d'erreur

Une erreur répond avec ce corps :

{
  "erreur": { "code": "scope_absent", "message": "..." }
}

Quota et limitation de débit

Chaque clé est bornée à un nombre d'appels par heure — son quota, fixé à la création de la clé. Le compte se fait sur une fenêtre glissante de 3600 secondes : ce sont les appels des 1 dernière(s) heure(s) écoulée(s) qui comptent, pas ceux depuis le début de l'heure d'horloge.

Trois en-têtes accompagnent toute réponse dès qu'une clé a été authentifiée, qu'elle soit acceptée ou refusée pour dépassement :

Le quota dépassé répond 429 avec le code d'erreur quota_depasse, et porte lui aussi les trois en-têtes ci-dessus — X-RateLimit-Remaining à zéro, X-RateLimit-Reset dans le futur.

Ressources disponibles

Chaque ressource expose deux points d'accès en GET : la collection et l'élément. Trois d'entre elles — absences, bulletins, paiements — exposent en plus des écritures ciblées, listées dans la section suivante.

Écritures disponibles

Chacune est un acte métier — « enregistrer un paiement », « publier un bulletin » — jamais un CRUD générique : ce dépôt n'expose ni PUT ni DELETE génériques sur une ligne. Une écriture peut exiger un scope distinct de celui de la lecture — parfois même distinct d'une autre écriture de la même ressource, pour qu'une clé qui corrige une appréciation ne puisse pas pour autant publier un bulletin.

Ce que l'API ne fait pas (encore)

• Les écritures se limitent aux sept actes listés plus haut : aucun PUT ni DELETE génériques, et la plupart des ressources restent en lecture seule.
• La pagination est par décalage (offset), pas par curseur. Une ligne insérée entre deux appels décale d'un rang tout ce qui suit : un client qui feuillette une collection peut donc recevoir la même donnée deux fois — la dernière de la page N, puis la première de la page N+1. C'est un compromis connu et assumé, pas un défaut caché ; il n'y a pas de tri ni de filtre pour l'atténuer dans cette version.