REST API Wise Timetable

Îl puteți inspecta chiar acum

Descrierea serviciului nu necesită credențiale, astfel că prima întrebare a unui dezvoltator își găsește răspunsul într-o singură linie.

GET https://wise-tt.com/api/v2/meta returnează numele serviciului, versiunea și lista endpointurilor pe care serverul le oferă în prezent. Fără token, fără cont, fără apel de vânzări — deschideți-l într-un browser. Este și modul cinstit de a descoperi orice a fost adăugat după ultima revizuire a manualului.

Manualul de integrare este publicat integral, fără formular, cu parametrii fiecărui endpoint, un exemplu realist de răspuns pentru fiecare și exemple complete funcționale în curl, Python, JavaScript și C. Îl publicăm deoarece o integrare care pare fezabilă pe hârtie și se dovedește că nu este reprezintă o descoperire mult mai costisitoare în luna a treia.

Citirea datelor necesită, într-adevăr, un cont API, emis de noi și limitat la școlile pe care are voie să le citească. Această parte este deliberată: un orar spune cine ce predă și ce studenți îl frecventează.

Ce expune API-ul

• Orare, pe grupă de studenți, cadru didactic, sală sau curs — sau pentru întreaga școală deodată
• Detalii complete pentru un singur eveniment, inclusiv ierarhia de program, an, ramură și grupă din spatele fiecărei grupe care îl frecventează
• Limitele anului universitar publicat, astfel încât un client să poată împiedica utilizatorul să navigheze în săptămâni care nu pot conține date
• Zile libere, astfel încât o zi goală să fie citită ca zi liberă, nu ca date lipsă
• Notificări atașate unei școli, unei grupe, unui curs sau unui cadru didactic, deduplicate și returnate ca obiecte structurate
• Liste de coduri pentru programe, ramuri, grupe, cadre didactice, săli și cursuri — id-urile și etichetele din care se construiește un selector
• Capacitatea sălii, codul sălii și căsuța poștală proprie a sălii școlii, acolo unde școala le-a completat
• Orarul de clopoțel al școlii, deoarece duratele intervalelor nu sunt aceleași peste tot
• Numerele de săptămână proprii școlii și denumirea proprie a școlii pentru o săptămână, acolo unde are una — un număr de săptămână în acest produs nu este săptămâna ISO a anului calendaristic și niciun client nu ar trebui vreodată să calculeze una
• Tipurile de rezervare folosite de o școală și sălile pe care fiecare cadru didactic are voie să le rezerve, pentru un client care oferă și rezervare, nu doar citire
• Ce permite fiecare școală unui client să ofere, astfel încât un selector de răsfoire după cadru didactic să fie ascuns acolo unde angajamentele cadrelor didactice sunt tratate ca date confidențiale
• Liste de prezență, acolo unde o instituție ține prezența prin cod QR — lista fiecărei ore în întregime, pe date pentru o primă completare și apoi tot ce s-a schimbat de la ultimul apel, pentru un sistem de evidență a studenților. Date personale despre studenți, deci un cont le citește doar cu o permisiune proprie

Rezervări de săli, făcute de o persoană, nu de un cont

Rezervarea este singura parte a API-ului care nu folosește deloc un cont de integrare, iar motivul merită spus pe față: o rezervare este făcută de cineva, iar orarul înregistrează cine. Un membru al personalului se autentifică cu propriul nume de utilizator și parolă, primește un token care numește o singură școală și durează opt ore și creează, modifică și șterge rezervări în nume propriu — motiv pentru care o credențială compilată într-o aplicație publicată nu poate ajunge niciodată la această suprafață.

Înainte de a scrie ceva, un client poate întreba dacă un tipar este liber. GET /v2/free-busy extinde în fiecare a doua marți din martie până în mai, 08:00–10:00, sala B-004 în date reale și raportează, dată cu dată, ce stă deja în cale — și dacă este vorba despre sală, cadrul didactic sau grupă. O suprapunere este refuzată cu datele în conflict atașate, nu cu un simplu nu, împreună cu cele mai apropiate ore de început și cu celelalte săli libere în fiecare dintre acele date. Un planificator care insistă poate totuși rezerva peste suprapunere, iar aceasta este înregistrată ca decizie deliberată, nu ascunsă.

Întreaga suprafață — autentificarea unei persoane, tipurile de rezervare ale școlii, lista albă de săli a fiecărui cadru didactic, disponibilitatea și crearea, modificarea și ștergerea unei rezervări — constituie capitolul 13 al manualului, cu un exemplu lucrat care merge de la autentificare până la o sală rezervată.

Construit pentru un client care interoghează periodic

Fiecare răspuns poartă un ETag. Repetați cererea cu If-None-Match, iar un orar neschimbat răspunde cu 304, fără corp, ceea ce este cazul obișnuit pentru un ecran dintr-un hol care se reîmprospătează la câteva minute. Un client bine educat transferă aproape nimic într-o zi liniștită.

Credențialele sunt schimbate o singură dată pentru un token bearer care durează 24 de ore și codifică școlile pe care are voie să le citească. Aplicațiile de browser sunt acceptate printr-o listă explicită de origini permise, nu printr-un wildcard — spuneți-ne de la ce origine este servit tabloul dumneavoastră de bord și este adăugată.

Interfața mai veche este încă servită și încă înghețată

Instituțiilor care s-au integrat cu API-ul anterior nu li s-a stricat integrarea de către v2. Căile vechi sunt încă servite și sunt înghețate în mod deliberat, iar v2 păstrează intenționat denumirile vechi ale câmpurilor — astfel încât trecerea la v2 înseamnă schimbarea unui URL, nu a unui parser, iar câmpurile pe care le adaugă v2 sunt adaosuri, nu înlocuiri.

Aceasta este întreaga politică într-o propoziție: un API pe care o universitate își construiește aplicațiile este o promisiune, iar încălcarea ei pentru a ordona denumirile câmpurilor nu este o economie.