Référence — conventions

Ce qui vaut pour toutes les routes de l'API : l'adresse, l'authentification, les types de données, la pagination, la taille des corps et les limites de débit. Chaque page de la référence s'appuie sur ces définitions.

Toutes les routes

Une seule API, /api, pour l'application, le logiciel d'un établissement et celui d'un éditeur partenaire. Cette table est générée depuis les déclarations qui gardent les routes : elle ne peut pas diverger de l'API.

La colonne « Exige » dit ce que l'appelant doit pouvoir faire. Une capacité d'établissement (schedule.read, institution.manage…) se mesure dans l'établissement désigné par l'adresse ; « ou » sépare des capacités dont une seule suffit.

Les anciennes adresses /api/integration/… et /api/partner/… répondent encore, comme alias dépréciés de ces routes : chaque réponse porte l'en-tête Deprecation: true et un en-tête Link vers la route qui la remplace, par exemple Link: </api/institutions/…/lessons>; rel="successor-version". Elles n'acceptent que leur propre sorte de clé — mhk_… pour la première, mhp_… pour la seconde — et disparaîtront à la prochaine version.

Adresse de base

Toutes les routes sont relatives au domaine de votre instance, par exemple https://reunion.votre-etablissement.fr. En production, l'API n'est servie qu'en HTTPS.

Version

La version de l'API se dit dans un en-tête, pas dans l'adresse : une ressource garde la même adresse d'une version à l'autre, et c'est votre programme qui dit quel contrat il attend.

Api-Version: 1

• Absent, l'en-tête vaut la version courante, 1. Un lien ouvert dans un navigateur — une feuille de présence, un export — n'en porte pas, et fonctionne.
• Envoyez-le quand même depuis vos programmes : le jour où une version 2 sortira, un programme qui demande 1 continuera de recevoir le contrat qu'il connaît.
• Une version que l'instance ne sert pas est refusée, plutôt que servie à la place d'une autre sans le dire :

Le corps du refus porte aussi supported, la liste des versions servies. Chaque réponse de l'API porte l'en-tête Api-Version, la version qui l'a servie. La version est un entier : on fige un contrat, pas un correctif.

Authentification

Une seule porte, et un seul justificatif par requête : la session d'une personne, la clé du logiciel d'un établissement (mhk_…) ou celle d'un éditeur partenaire (mhp_…). Une requête qui porte à la fois le cookie de session et un en-tête Authorization est refusée (400, code auth.ambiguous) : elle n'est pas départagée.

L'établissement d'un appel se lit dans l'adresse : /api/institutions/:institutionId/…. Un établissement que l'appelant n'atteint pas répond 404, code not-found, comme s'il n'existait pas. Une route qui demande une capacité que l'appelant n'a pas dans cet établissement répond 403, code forbidden, et le message nomme ce qu'il faudrait : cet accès ne permet pas cela — il faut : schedule.read.

Une écriture faite avec le cookie de session doit venir des pages de MeetingHub : une écriture qui porte l'en-tête Origin d'un autre site est refusée (403, code origin.refused). Un client sans en-tête Origin, comme curl, n'est pas concerné.

La clé d'intégration

Authorization: Bearer mhk_Abdvt1rV_47R9xK2pQ…

La clé est vérifiée à chaque requête : une révocation prend effet à la requête suivante. Les réponses d'échec sont décrites sur la page Clés d'intégration.

GET /api/me

Rend l'appelant et ce qu'il peut faire. Aucune capacité n'est demandée ; sans justificatif, la réponse est { "actor": { "kind": "anonymous" } }.

Réponse 200, pour une clé d'établissement :

{
  "actor": { "kind": "institution-key", "id": "…", "name": "ENT — émargement" },
  "institutions": [{ "id": "6c1d3a52-…", "name": "Lycée bilingue", "status": "active" }],
  "capabilities": ["institution.view", "attendance.read"]

}

Ouvrir une session d'administrateur

POST /api/auth/signin — sans authentification. C'est ainsi qu'un administrateur appelle l'API avec sa session, par exemple pour poser une clé.

Réponse 200, avec l'en-tête Set-Cookie: meetinghub.sid=… :

{
  "user": {
    "id": "5a74f72e-81af-402c-a2af-a5ebd35b7bba",
    "email": "direction@mon-lycee.fr",
    "phone": null,
    "displayName": "Direction",
    "platformAdmin": false,
    "orgId": "6c1d3a52-7a0e-4f0b-9c55-0a54c3e1f2b8",
    "orgRole": "admin",
    "capabilities": ["institution.view", "institution.manage", "…"],
    "institution": { "id": "6c1d3a52-…", "name": "Lycée bilingue", "status": "active", "…": "…" }
  }

}

Le cookie est à renvoyer avec chaque requête. Sur /api, l'établissement actif ne décide de rien : c'est l'adresse qui désigne l'établissement, et le rôle qu'on y tient qui ouvre les routes.

Types de données

Tous les corps sont du JSON encodé en UTF-8, sauf l'export CSV et la page imprimable d'une feuille de présence. Une requête avec un corps doit porter Content-Type: application/json.

Un champ qui peut valoir null est noté « string ou null » dans la colonne Type.

Dates. En réponse, toutes les dates sont en UTC, avec les millisecondes et le suffixe Z. En requête, écrivez-les au même format : une date sans fuseau serait lue dans le fuseau du serveur.

Identifiants. Les objets de MeetingHub sont désignés par un uuid. Un uuid mal formé dans un chemin rend 404, comme un uuid inconnu. Vos propres objets — cours, salles, classes — sont désignés par votre identifiant, appelé ref : une string de 1 à 200 caractères, espaces de bord retirés. Au-delà de 200 caractères, elle est tronquée.

Champs inconnus. Un champ que la route n'attend pas est ignoré, sans erreur. Un champ attendu mais d'un autre type que celui documenté est traité comme absent.

Pagination

Les listes longues — le journal d'une clé et la liste des membres — se lisent par tranches, avec trois paramètres de requête :

La réponse porte les éléments et le total :

Taille des corps

Un corps plus gros rend 413, un JSON illisible 400 : voir Corps illisible ou trop gros.

Limites de débit

Au-delà, la réponse est 429, avec un en-tête Retry-After qui donne, en secondes, le temps à attendre avant la prochaine tentative. L'exploitant d'une instance peut relever ces limites ; il ne peut pas les baisser sous ces valeurs.