L’API REST de Wise Timetable

Vous pouvez l’inspecter dès maintenant

La description du service ne demande aucun identifiant, de sorte que la première question d’un développeur trouve réponse en une ligne.

GET https://wise-tt.com/api/v2/meta renvoie le nom du service, la version et la liste des points d’accès que le serveur sert actuellement. Pas de jeton, pas de compte, pas d’appel commercial — ouvrez-le dans un navigateur. C’est aussi la manière honnête de découvrir tout ce qui a été ajouté depuis la dernière révision du manuel.

Le manuel d’intégration est publié en intégralité, sans formulaire, avec les paramètres de chaque point d’accès, un exemple de réponse réaliste pour chacun et des exemples complets fonctionnels en curl, Python, JavaScript et C. Nous le publions parce qu’une intégration qui paraît faisable sur le papier et qui se révèle ne pas l’être est une découverte bien plus coûteuse au troisième mois.

La lecture des données exige bien un compte d’API, délivré par nous et limité aux établissements qu’il peut lire. C’est volontaire : un emploi du temps indique qui enseigne quoi et quels étudiants y assistent.

Ce que l’API expose

• Les plannings, par groupe d’étudiants, enseignant, salle ou cours — ou pour tout l’établissement à la fois
• Le détail complet d’un événement unique, y compris la hiérarchie programme, année, filière et groupe derrière chaque groupe qui y assiste
• Les bornes de l’année universitaire publiée, afin qu’un client puisse empêcher l’utilisateur de naviguer vers des semaines qui ne peuvent contenir aucune donnée
• Les jours fériés, afin qu’un jour vide se lise comme un jour férié plutôt que comme une donnée manquante
• Les notifications rattachées à un établissement, un groupe, un cours ou un enseignant, dédoublonnées et renvoyées sous forme d’objets structurés
• Les listes de codes des programmes, filières, groupes, enseignants, salles et cours — les identifiants et libellés à partir desquels un sélecteur est construit
• La capacité des salles, le code de salle et la boîte aux lettres propre à la salle de l’établissement, lorsque celui-ci les a renseignés
• La grille horaire des sonneries de l’établissement, car la durée des créneaux n’est pas la même partout
• Les propres numéros de semaine de l’établissement, et le propre nom qu’il donne à une semaine lorsqu’il en a un — un numéro de semaine dans ce produit n’est pas la semaine ISO de l’année civile, et aucun client ne devrait jamais en calculer une
• Les types de réservation qu’utilise un établissement et les salles que chaque enseignant est autorisé à réserver, pour un client qui propose la réservation en plus de la lecture
• Ce que chaque établissement autorise un client à proposer, de sorte qu’un sélecteur de consultation par enseignant soit masqué là où les engagements des enseignants sont traités comme confidentiels
• Les listes de présence, lorsqu’un établissement relève la présence par QR code — la liste de chaque cours en entier, par dates pour un premier remplissage puis ce qui a changé depuis le dernier appel, pour un système d’information étudiant. Ce sont des données personnelles sur les étudiants : un compte ne les lit qu’avec une autorisation spécifique

Réservations de salles, faites par une personne plutôt que par un compte

La réservation est la seule partie de l’API qui ne demande aucun compte d’intégration, et la raison mérite d’être énoncée clairement : une réservation est faite par quelqu’un, et l’emploi du temps enregistre qui. Un membre du personnel se connecte avec son propre nom d’utilisateur et mot de passe, reçoit un jeton qui désigne un seul établissement et dure huit heures, et crée, modifie et supprime des réservations en son propre nom — ce qui explique aussi pourquoi un identifiant compilé dans une application publiée ne peut jamais atteindre cette surface.

Avant d’écrire quoi que ce soit, un client peut demander si un schéma est libre. GET /v2/free-busy développe un mardi sur deux de mars à mai, 08:00–10:00, salle B-004 en dates réelles et indique, date par date, ce qui gêne déjà — et s’il s’agit de la salle, de l’enseignant ou du groupe. Un conflit est refusé avec les dates en conflit jointes, et non par un simple non, accompagné des heures de début les plus proches et des autres salles libres à chacune de ces dates. Un planificateur qui y tient peut malgré tout réserver par-dessus le conflit, et cela est consigné comme une décision délibérée plutôt que dissimulé.

L’ensemble de la surface — connexion d’une personne, types de réservation de l’établissement, liste blanche de salles de chaque enseignant, disponibilité, et création, modification et suppression d’une réservation — fait l’objet du chapitre 13 du manuel, avec un exemple commenté qui va de la connexion à une salle réservée.

Conçue pour un client qui interroge régulièrement

Chaque réponse porte un ETag. Répétez la requête avec If-None-Match et un emploi du temps inchangé répond 304 sans aucun corps, ce qui est le cas courant d’un écran de hall qui se rafraîchit toutes les quelques minutes. Un client bien conçu ne transfère presque rien un jour calme.

Les identifiants sont échangés une seule fois contre un jeton porteur valable 24 heures et qui encode les établissements qu’il peut lire. Les applications de navigateur sont prises en charge via une liste blanche explicite d’origines plutôt qu’un joker — indiquez-nous l’origine d’où votre tableau de bord est servi et elle sera ajoutée.

L’ancienne interface est toujours servie, et toujours figée

Les établissements qui s’étaient intégrés à l’API précédente n’ont pas vu leur intégration cassée par la v2. Les chemins hérités sont toujours servis et délibérément figés, et la v2 conserve volontairement les noms de champs hérités — passer à la v2 est donc un changement d’URL plutôt que d’analyseur, et les champs ajoutés par la v2 sont des ajouts plutôt que des remplacements.

C’est toute la politique en une phrase : une API sur laquelle une université construit est une promesse, et la rompre pour ranger des noms de champs n’est pas une économie.