Integracija

REST API sistema Wise Timetable

Sve što Wise Timetable objavljuje može se čitati kao JSON preko HTTPS-a — iz Vašeg portala, VLE-a, Vaše vlastite aplikacije, informativnog ekrana ili alata za izvještavanje. Priručnik je javan, pa Vaši programeri mogu procijeniti integraciju prije nego što iko išta potpiše.

Zakažite online demonstraciju Preuzmite besplatnu probnu verziju

API v2, JSON preko HTTPS-a
Potpun priručnik, bez prijave
ETag keširanje, 304 kada se ništa nije promijenilo

Možete ga pregledati upravo sada

Opis servisa ne treba pristupne podatke, pa je prvo pitanje koje programer postavlja moguće odgovoriti u jednom retku.

GET https://wise-tt.com/api/v2/meta vraća naziv servisa, verziju i listu krajnjih tačaka koje server trenutno servira. Bez tokena, bez računa, bez poziva prodaji — otvorite ga u pregledniku. To je i iskren način da se otkrije sve što je dodano nakon posljednje revizije priručnika.

Priručnik za integraciju objavljen je u cijelosti, bez prijave, s parametrima svake krajnje tačke, realističnim primjerom odgovora za svaku i potpunim radnim primjerima u curlu, Pythonu, JavaScriptu i C-u. Objavljujemo ga jer je integracija koja na papiru izgleda izvedivo, a ispostavi se da nije, daleko skuplje otkriće u trećem mjesecu.

Čitanje podataka zaista zahtijeva API račun, koji izdajemo mi, ograničen na škole koje smije čitati. Taj dio je namjeran: raspored navodi ko šta predaje i koji studenti to pohađaju.

Jedan zahtjev po prikazu, a ne lanac njih

GET /v2/schedule prima školu, vremenski raspon i ono što pratite — grupe, nastavnika, prostoriju, predmet ili ništa za cijelu školu — i vraća svaki događaj u rasponu s već popunjenim prostorijama, nastavnicima, grupama i smjerovima, zajedno s praznicima škole i granicama objavljene akademske godine. Nema naknadnih poziva za pretvaranje id-ova u nazive.

Izmjereno na najvećoj školi na serveru, jedna sedmica iznosi oko 100 kB i 75 ms. Raspon je ograničen na 400 dana po zahtjevu, što najgori slučaj čini poznatim, a ne iznenađenjem na dan kada neko zatraži deset godina.

Id-ovi događaja nose svoju vrstu u prvom znaku: S za raspoređeno predavanje, R za rezervaciju — ispit, rezervaciju prostorije, sastanak, laboratorijski termin.

Šta API izlaže

Rasporedi, po studentskoj grupi, nastavniku, prostoriji ili predmetu — ili cijela škola odjednom
Puni detalji za pojedinačni događaj, uključujući hijerarhiju programa, godine, smjera i grupe iza svake grupe koja ga pohađa
Granice objavljene akademske godine, pa klijent može spriječiti korisnika da navigira u sedmice koje ne mogu imati podataka
Praznici, pa prazan dan izgleda kao praznik, a ne kao podaci koji nedostaju
Obavijesti vezane za školu, grupu, predmet ili nastavnika, deduplicirane i vraćene kao strukturirani objekti
Šifrarnici programa, smjerova, grupa, nastavnika, prostorija i predmeta — id-ovi i oznake iz kojih se gradi birač
Kapacitet prostorije, šifra prostorije i vlastito poštansko sanduče škole za prostoriju, gdje ih je škola popunila
Raspored zvona škole, jer dužine termina nisu svugdje iste
Vlastiti brojevi sedmica škole i vlastiti naziv škole za sedmicu gdje ga ima — broj sedmice u ovom proizvodu nije ISO sedmica kalendarske godine i nijedan klijent ga nikada ne bi trebao računati
Vrste rezervacija koje škola koristi i prostorije koje svaki nastavnik smije rezervirati, za klijenta koji nudi i rezervaciju, a ne samo čitanje
Šta svaka škola dopušta klijentu da ponudi, pa se birač po nastavniku sakriva gdje se angažmani nastavnika tretiraju kao povjerljivi
Liste prisustva, gdje institucija vodi evidenciju prisustva putem QR koda — lista svakog predavanja u cijelosti, po datumima za prvo punjenje, a zatim sve što se promijenilo od posljednjeg poziva, za studentski informacioni sistem. Lični podaci o studentima, pa ih račun čita samo uz vlastitu dozvolu

I dijelovi u koje možete pisati

API je pretežno za čitanje i svaki izuzetak je imenovan. POST /v2/eventlinks vezuje vezu za online sastanak za pojedinačne događaje prema njihovom stabilnom identifikatoru — veza preživljava sljedeću ponovnu objavu iz desktop aplikacije, a veza koju je unio izrađivač rasporeda ima prednost nad poslanom. POST /v2/student-registration omogućava studentskom informacionom sistemu da navede kojim grupama i polaganjima predmeta student pripada. PUT /v2/lecturer-language postavlja jezik na kojem je napisan PDF rasporeda samog nastavnika, za institucije koje predaju na više od jednog jezika.

Svaki od njih je isključen osim ako je Vaš račun izričito ovlašten da ga koristi, a svaki prijavljuje rezultate po stavci, a ne otkazuje cijelu seriju zato što je jedna šifra predmeta pogrešno ukucana.

Rezervacije prostorija, koje pravi osoba, a ne račun

Rezervacija je jedini dio API-ja koji uopće ne uzima integracijski račun, a razlog vrijedi jasno reći: rezervaciju pravi neko, a raspored bilježi ko. Član osoblja se prijavljuje vlastitim korisničkim imenom i lozinkom, dobija token koji imenuje jednu školu i traje osam sati, te kreira, mijenja i briše rezervacije kao on sam — zbog čega pristupni podatak ugrađen u objavljenu aplikaciju nikada ne može doseći ovu površinu.

Prije bilo kakvog pisanja klijent može pitati je li obrazac slobodan. GET /v2/free-busy razvija svaki drugi utorak od marta do maja, 08:00–10:00, prostorija B-004 u stvarne datume i izvještava, datum po datum, šta je već na putu — i je li to prostorija, nastavnik ili grupa. Sudar se odbija s priloženim datumima sudara, a ne običnim ne, zajedno s najbližim početnim vremenima i drugim prostorijama koje su slobodne na svaki od tih datuma. Planer koji to misli ozbiljno ipak može rezervirati preko sudara, a to se bilježi kao namjerna odluka, a ne skriva.

Cijela površina — prijava osobe, vrste rezervacija škole, popis dozvoljenih prostorija svakog nastavnika, dostupnost te kreiranje, mijenjanje i brisanje rezervacije — je poglavlje 13 priručnika, s radnim primjerom koji ide od prijave do rezervirane prostorije.

Napravljeno za klijenta koji često provjerava

Svaki odgovor nosi ETag. Ponovite zahtjev s If-None-Match i neizmijenjen raspored odgovara s 304 bez ikakvog tijela, što je uobičajen slučaj za ekran u predvorju koji se osvježava svakih nekoliko minuta. Dobro odgojen klijent na mirnom danu prenosi gotovo ništa.

Pristupni podaci se jednom razmjenjuju za bearer token koji traje 24 sata i kodira škole koje smije čitati. Preglednička aplikacija podržana je putem izričite liste dozvoljenih izvora, a ne zamjenskog znaka — recite nam izvor s kojeg se servira Vaša nadzorna ploča i bit će dodan.

Greške koje kažu šta je pošlo po zlu

Pogrešno ukucana šifra škole, škola koju Vaš račun ne smije čitati i sedmica koja zaista nema predavanja su tri različite situacije, a integracija koja prikazuje istu poruku za sve tri troši nečije popodne. To su 400 unknown_school, 403 school_not_permitted i sasvim običan 200 s praznom listom.

Svaki neuspjeh vraća stabilan strojno čitljiv kod greške, rečenicu na engleskom i često savjet. 500 nosi referentni id; navedite ga i tačne linije dnevnika mogu se odmah pronaći.

Stariji interfejs se i dalje servira i dalje je zamrznut

Institucijama koje su se integrirale prema ranijem API-ju v2 nije pokvario integraciju. Naslijeđene putanje se i dalje serviraju i namjerno su zamrznute, a v2 namjerno zadržava naslijeđene nazive polja — pa je prelazak na v2 promjena URL-a, a ne promjena parsera, a polja koja v2 dodaje su dodaci, a ne zamjene.

To je cijela politika u jednoj rečenici: API prema kojem univerzitet gradi je obećanje, a njegovo kršenje radi uređivanja naziva polja nije ušteda.

Preuzmite priručnik za API

Pogledajte Wise Timetable na svojim podacima

Zakažite online prezentaciju od 45 minuta. Proći ćemo kroz problem raspoređivanja u Vašoj ustanovi, pokazati kako ga Wise Timetable rješava i odgovoriti na sve što Vaš tim želi testirati.