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, sopstvene aplikacije, informativnog ekrana ili alata za izveštavanje. Priručnik je javan, pa Vaši programeri mogu da procene integraciju pre nego što iko išta potpiše.

Zakažite onlajn demonstraciju Preuzmite besplatnu probnu verziju

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

Možete ga pregledati odmah

Opis servisa ne zahteva pristupne podatke, pa se prvo pitanje koje programer postavlja može rešiti jednim redom.

GET https://wise-tt.com/api/v2/meta vraća naziv servisa, verziju i spisak endpointa koje server trenutno služi. Bez tokena, bez naloga, bez razgovora sa prodajom — otvorite ga u pregledaču. To je i pošten način da se otkrije sve što je dodato nakon poslednje revizije priručnika.

Priručnik za integraciju objavljen je u celosti, bez prijave, sa parametrima svakog endpointa, realističnim primerom odgovora za svaki i potpunim radnim primerima u curl-u, Python-u, JavaScript-u i C-u. Objavljujemo ga jer je integracija koja na papiru izgleda izvodljivo, a ispostavi se da nije, daleko skuplje otkriće u trećem mesecu.

Za čitanje podataka je potreban API nalog, koji izdajemo mi i koji je ograničen na škole koje sme da čita. Taj deo je nameran: raspored navodi ko šta predaje i koji studenti ga pohađaju.

Jedan zahtev po prikazu, a ne lanac zahteva

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

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

Id-jevi događaja nose svoju vrstu u prvom znaku: S za čas u rasporedu, R za rezervaciju — ispit, rezervaciju prostorije, sastanak, laboratorijsku vežbu.

Šta API izlaže

Rasporede, po studentskoj grupi, nastavniku, prostoriji ili predmetu — ili celu školu odjednom
Pune detalje jednog događaja, uključujući hijerarhiju programa, godine, smera i grupe iza svake grupe koja ga pohađa
Granice objavljene akademske godine, pa klijent može da spreči korisnika da ode u nedelje koje ne mogu da sadrže podatke
Praznike, pa prazan dan izgleda kao praznik, a ne kao podaci koji nedostaju
Obaveštenja vezana za školu, grupu, predmet ili nastavnika, bez duplikata i vraćena kao strukturirani objekti
Šifarnike programa, smerova, grupa, nastavnika, prostorija i predmeta — id-jeve i oznake od kojih se gradi birač
Kapacitet prostorije, šifru prostorije i sopstveno poštansko sanduče prostorije škole, tamo gde ih je škola popunila
Raspored zvona škole, jer dužine termina nisu svuda iste
Sopstvene brojeve nedelja škole i sopstveni naziv škole za nedelju tamo gde ga ima — broj nedelje u ovom proizvodu nije ISO nedelja kalendarske godine i nijedan klijent ga nikada ne bi trebalo da računa
Vrste rezervacija koje škola koristi i prostorije koje svaki nastavnik sme da rezerviše, za klijenta koji nudi rezervaciju, a ne samo čitanje
Šta svaka škola dopušta klijentu da ponudi, pa se birač po nastavniku skriva tamo gde se angažmani nastavnika tretiraju kao poverljivi
Spiskove prisustva, tamo gde institucija vodi prisustvo preko QR koda — spisak svakog časa u celosti, po datumima za prvo punjenje, a zatim sve što se promenilo od poslednjeg poziva, za studentski informacioni sistem. Lični podaci o studentima, pa ih nalog čita samo uz sopstvenu dozvolu

I delovi u koje možete da pišete

API je pretežno za čitanje i svaki izuzetak je imenovan. POST /v2/eventlinks vezuje vezu ka onlajn sastanku za pojedinačne događaje preko njihovog stabilnog identifikatora — veza preživljava sledeće ponovno objavljivanje iz desktop aplikacije, a veza koju je uneo planer pobeđuje poslatu. POST /v2/student-registration omogućava studentskom informacionom sistemu da navede kojim grupama i ispitnim terminima student pripada. PUT /v2/lecturer-language postavlja jezik na kojem se piše PDF rasporeda samog nastavnika, za institucije koje predaju na više od jednog jezika.

Svaki od njih je isključen osim ako Vaš nalog nije izričito ovlašćen da ga koristi, i svaki javlja rezultate po stavci, umesto da propadne cela serija zbog jedne pogrešno otkucane šifre predmeta.

Rezervacije prostorija, pravi čovek, a ne nalog

Rezervacija je jedini deo API-ja koji uopšte ne uzima integracioni nalog, a razlog vredi izreći jasno: rezervaciju pravi neko, a raspored beleži ko. Zaposleni se prijavljuje sopstvenim korisničkim imenom i lozinkom, dobija token koji imenuje jednu školu i traje osam sati, i pravi, menja i briše rezervacije kao on sam — zbog čega pristupni podatak kompajliran u objavljenu aplikaciju nikada ne može da dosegne ovu površinu.

Pre nego što bilo šta upiše, klijent može da pita da li je neki obrazac slobodan. GET /v2/free-busy razvija svakog drugog utorka od marta do maja, 08:00–10:00, prostorija B-004 u prave datume i izveštava, datum po datum, šta je već na putu — i da li je to prostorija, nastavnik ili grupa. Sukob se odbija sa priloženim datumima sukoba, a ne golim ne, zajedno sa najbližim početnim vremenima i drugim prostorijama koje su slobodne na svaki od tih datuma. Planer koji to zaista misli i dalje može da rezerviše preko sukoba, a to se beleži kao namerna odluka, a ne skriva.

Cela površina — prijava osobe, vrste rezervacija škole, spisak dozvoljenih prostorija svakog nastavnika, raspoloživost i pravljenje, menjanje i brisanje rezervacije — jeste 13. poglavlje priručnika, sa radnim primerom od prijave do rezervisane prostorije.

Napravljeno za klijenta koji često proverava

Svaki odgovor nosi ETag. Ponovite zahtev sa If-None-Match i nepromenjen raspored odgovara sa 304 bez ikakvog tela, što je uobičajen slučaj za ekran u foajeu koji se osvežava na svakih nekoliko minuta. Dobro vaspitan klijent u mirnom danu prenosi gotovo ništa.

Pristupni podaci se jednom menjaju za bearer token koji traje 24 sata i kodira škole koje sme da čita. Veb aplikacije su podržane preko izričite liste dozvoljenih izvora, a ne džokera — recite nam iz kog izvora se služi Vaša kontrolna tabla i biće dodat.

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

Pogrešno otkucana šifra škole, škola koju Vaš nalog ne sme da čita i nedelja koja zaista nema časova tri su različite situacije, a integracija koja za sve tri prikazuje istu poruku troši nečije popodne. To su 400 unknown_school, 403 school_not_permitted i sasvim obično 200 sa praznom listom.

Svaka greška vraća stabilan mašinski čitljiv kod greške, rečenicu na engleskom i često savet. 500 nosi referentni id; navedite ga i tačne redove dnevnika mogu odmah da se pronađu.

Starija površina se i dalje služi i i dalje je zamrznuta

Institucijama koje su se integrisale sa ranijim API-jem v2 nije pokvario integraciju. Stare putanje se i dalje služe i namerno su zamrznute, a v2 namerno zadržava stara imena polja — pa je prelazak na v2 promena URL-a, a ne promena parsera, a polja koja v2 dodaje jesu dodaci, a ne zamene.

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

Preuzmite API priručnik

Pogledajte Wise Timetable na Vašim sopstvenim podacima

Zakažite onlajn prezentaciju od 45 minuta. Proći ćemo kroz problem rasporeda Vaše ustanove, pokazati kako ga Wise Timetable rešava i odgovoriti na sve što Vaš tim želi da testira.