Integracija

REST API sustava Wise Timetable

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

Rezervirajte online demonstraciju Preuzmite besplatnu probnu verziju

API v2, JSON preko HTTPS-a
Cjeloviti priručnik, bez prijave
ETag predmemoriranje, 304 kad se ništa nije promijenilo

Možete ga pregledati odmah

Opis usluge ne traži vjerodajnice, pa je prvo pitanje koje programer postavlja odgovorivo u jednom retku.

GET https://wise-tt.com/api/v2/meta vraća naziv usluge, verziju i popis krajnjih točaka koje poslužitelj trenutno poslužuje. Bez tokena, bez računa, bez prodajnog poziva — otvorite ga u pregledniku. To je ujedno 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 točke, realističnim primjerom odgovora za svaku i cjelovitim radnim primjerima u curlu, Pythonu, JavaScriptu i C-u. Objavljujemo ga jer je integracija koja na papiru izgleda izvedivo, a pokaže se da nije, daleko skuplje otkriće u trećem mjesecu.

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

Jedan zahtjev po prikazu, a ne lanac njih

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

Izmjereno na najvećoj školi na poslužitelju, jedan tjedan iznosi oko 100 kB i 75 ms. Raspon je ograničen na 400 dana po zahtjevu, zbog čega je najgori slučaj poznat, a ne iznenađenje na dan kad netko zatraži desetljeće.

ID-evi događaja nose vrstu u prvom znaku: S za rasporedom predviđenu nastavu, R za rezervaciju — ispit, rezervaciju dvorane, sastanak, laboratorijsku vježbu.

Što API izlaže

Rasporedi, po studentskoj grupi, nastavniku, dvorani ili kolegiju — ili cijela škola odjednom
Puni detalji za pojedini 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 se kreće u tjedne koji ne mogu sadržavati podatke
Praznici, pa se prazan dan čita kao praznik, a ne kao podaci koji nedostaju
Obavijesti vezane uz školu, grupu, kolegij ili nastavnika, deduplicirane i vraćene kao strukturirani objekti
Popisi šifara za programe, smjerove, grupe, nastavnike, dvorane i kolegije — ID-evi i oznake od kojih se gradi birač
Kapacitet dvorane, šifra dvorane i vlastiti poštanski sandučić dvorane škole, gdje ih je škola ispunila
Raspored zvona škole, jer duljine termina nisu svugdje iste
Vlastiti brojevi tjedana škole i vlastiti naziv škole za tjedan gdje ga ima — broj tjedna u ovom proizvodu nije ISO tjedan kalendarske godine i nijedan ga klijent nikad ne bi smio izračunavati
Vrste rezervacija koje škola koristi i dvorane koje svaki nastavnik smije rezervirati, za klijenta koji uz čitanje nudi i rezerviranje
Što svaka škola dopušta klijentu da ponudi, pa se birač po nastavniku skriva tamo gdje se angažmani nastavnika tretiraju kao povjerljivi
Liste prisutnosti, gdje ustanova vodi prisutnost putem QR koda — lista svake nastave cijela, po datumima za prvo punjenje, a zatim sve što se promijenilo od posljednjeg poziva, za studentski informacijski sustav. Osobni podaci o studentima, pa ih račun čita samo uz vlastito dopuštenje

I dijelovi u koje možete pisati

API je pretežno za čitanje i svaka je iznimka imenovana. POST /v2/eventlinks pridružuje poveznicu za online sastanak pojedinim događajima prema njihovom stabilnom identifikatoru — poveznica preživljava sljedeću ponovnu objavu iz desktop aplikacije, a poveznica koju unese planer prevladava nad poslanom. POST /v2/student-registration omogućuje studentskom informacijskom sustavu da navede kojim grupama i ispitnim terminima kolegija student pripada. PUT /v2/lecturer-language postavlja jezik na kojem je napisan PDF vlastitog rasporeda nastavnika, za ustanove koje predaju na više od jednog jezika.

Svaki od njih isključen je osim ako Vaš račun nema izričito dopuštenje za njegovu uporabu, a svaki izvješćuje rezultate po stavci umjesto da odbije cijelu seriju zato što je jedna šifra kolegija pogrešno upisana.

Rezervacije dvorana, koje radi osoba, a ne račun

Rezerviranje je jedini dio API-ja koji uopće ne traži integracijski račun, a razlog je vrijedno jasno navesti: rezervaciju radi netko, a raspored bilježi tko. Djelatnik se prijavljuje vlastitim korisničkim imenom i lozinkom, prima token koji navodi jednu školu i traje osam sati te stvara, mijenja i briše rezervacije kao on sam — zbog čega vjerodajnica ugrađena u objavljenu aplikaciju nikad ne može doći do ove površine.

Prije pisanja bilo čega klijent može pitati je li obrazac slobodan. GET /v2/free-busy pretvara svaki drugi utorak od ožujka do svibnja, 08:00–10:00, dvorana B-004 u stvarne datume i izvješćuje, datum po datum, što je već na putu — i je li to dvorana, nastavnik ili grupa. Sukob se odbija uz priložene datume sukoba, a ne običnim ne, zajedno s najbližim početnim vremenima i drugim dvoranama koje su slobodne na svaki od tih datuma. Planer koji to doista misli i dalje može rezervirati povrh sukoba, a to se bilježi kao namjerna odluka, a ne skriva.

Cijela površina — prijava osobe, vrste rezervacija škole, popis dopuštenih dvorana svakog nastavnika, dostupnost te stvaranje, mijenjanje i brisanje rezervacije — poglavlje je 13 priručnika, s riješenim primjerom koji ide od prijave do rezervirane dvorane.

Izrađeno za klijenta koji često provjerava

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

Vjerodajnice se jednom razmjenjuju za bearer token koji traje 24 sata i kodira škole koje smije čitati. Preglednički programi podržani su putem izričitog popisa dopuštenih izvora, a ne zamjenskim znakom — recite nam izvor s kojeg se poslužuje Vaša nadzorna ploča i bit će dodan.

Pogreške koje kažu što je pošlo po zlu

Pogrešno upisana šifra škole, škola koju Vaš račun ne smije čitati i tjedan koji doista nema nastave tri su različite situacije, a integracija koja za sve tri prikazuje istu poruku traći nekome popodne. To su 400 unknown_school, 403 school_not_permitted i sasvim običan 200 s praznim popisom.

Svaki neuspjeh vraća stabilnu strojno čitljivu šifru pogreške, rečenicu na engleskom i često savjet. 500 nosi referentni ID; navedite ga i točne retke dnevnika mogu se odmah pronaći.

Starija površina i dalje se poslužuje i dalje je zamrznuta

Ustanovama koje su se integrirale s ranijim API-jem, v2 nije pokvario integraciju. Naslijeđene putanje i dalje se poslužuju 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 dodaci su, a ne zamjene.

To je cijela politika u jednoj rečenici: API na koji se sveučilište oslanja obećanje je, a njegovo kršenje radi uređivanja naziva polja nije ušteda.

Preuzmite API priručnik

Pogledajte Wise Timetable na svojim podacima

Rezervirajte 45-minutnu online prezentaciju. Proći ćemo kroz problem rasporeda Vaše ustanove, pokazati kako ga Wise Timetable rješava i odgovoriti na sve što Vaš tim želi testirati.