L’API REST di Wise Timetable

Potete ispezionarla subito

La descrizione del servizio non richiede credenziali, quindi la prima domanda di uno sviluppatore ha risposta in una riga.

GET https://wise-tt.com/api/v2/meta restituisce il nome del servizio, la versione e l’elenco degli endpoint che il server sta attualmente servendo. Nessun token, nessun account, nessuna telefonata commerciale — apritelo in un browser. È anche il modo onesto per scoprire qualsiasi cosa aggiunta dopo l’ultima revisione del manuale.

Il manuale di integrazione è pubblicato per intero, senza registrazione, con i parametri di ogni endpoint, una risposta di esempio realistica per ciascuno ed esempi completi e funzionanti in curl, Python, JavaScript e C. Lo pubblichiamo perché un’integrazione che sulla carta sembra fattibile e poi non lo è risulta una scoperta molto più costosa al terzo mese.

La lettura dei dati richiede invece un account API, rilasciato da noi e limitato alle scuole che può leggere. È una scelta deliberata: un orario indica chi insegna che cosa e quali studenti lo frequentano.

Che cosa espone l’API

• Orari, per gruppo di studenti, docente, aula o corso — oppure per l’intera scuola in una volta
• Dettaglio completo di un singolo evento, compresa la gerarchia di programma, anno, indirizzo e gruppo dietro ogni gruppo che vi partecipa
• I limiti dell’anno accademico pubblicato, così che un client possa impedire all’utente di spostarsi in settimane che non possono contenere dati
• Festività, così che un giorno vuoto sia letto come festività e non come dati mancanti
• Notifiche associate a una scuola, a un gruppo, a un corso o a un docente, deduplicate e restituite come oggetti strutturati
• Elenchi di codici per programmi, indirizzi, gruppi, docenti, aule e corsi — gli id e le etichette con cui si costruisce un selettore
• Capienza dell’aula, codice dell’aula e casella di posta propria dell’aula della scuola, dove la scuola li ha compilati
• Il quadro orario delle campanelle della scuola, perché la durata degli slot non è uguale ovunque
• I numeri di settimana propri della scuola e il nome che la scuola dà a una settimana dove ne ha uno — un numero di settimana in questo prodotto non è la settimana ISO dell’anno solare, e nessun client dovrebbe mai calcolarlo
• I tipi di prenotazione che una scuola usa e le aule che ciascun docente può riservare, per un client che offre anche la prenotazione oltre alla lettura
• Che cosa consente ciascuna scuola di offrire a un client, così che un selettore per docente sia nascosto dove gli incarichi dei docenti sono trattati come riservati
• Elenchi di presenza, dove un’istituzione rileva le presenze tramite codice QR — l’elenco di ogni lezione per intero, per date per un primo riempimento e poi quanto è cambiato dall’ultima chiamata, per un sistema informativo studenti. Dati personali degli studenti, quindi un account li legge solo con un permesso proprio

Prenotazioni di aule, effettuate da una persona e non da un account

La prenotazione è l’unica parte dell’API che non richiede affatto un account di integrazione, e il motivo vale la pena di dirlo chiaramente: una prenotazione è fatta da qualcuno e l’orario registra da chi. Un membro del personale accede con il proprio nome utente e la propria password, riceve un token che indica una sola scuola e dura otto ore, e crea, modifica ed elimina prenotazioni a proprio nome — ed è anche per questo che una credenziale compilata in un’app pubblicata non può mai raggiungere questa superficie.

Prima di scrivere qualsiasi cosa, un client può chiedere se uno schema è libero. GET /v2/free-busy espande un martedì sì e uno no da marzo a maggio, 08:00–10:00, aula B-004 in date reali e riporta, data per data, che cosa è già di intralcio — e se si tratta dell’aula, del docente o del gruppo. Una sovrapposizione viene rifiutata con le date in conflitto allegate anziché con un semplice no, insieme agli orari di inizio più vicini e alle altre aule libere in tutte quelle date. Un pianificatore che lo voglia davvero può comunque prenotare sopra la sovrapposizione, e ciò viene registrato come decisione deliberata anziché nascosto.

L’intera superficie — far accedere una persona, i tipi di prenotazione della scuola, l’elenco delle aule consentite a ciascun docente, la disponibilità, e la creazione, modifica ed eliminazione di una prenotazione — è il capitolo 13 del manuale, con un esempio svolto che va dall’accesso a un’aula prenotata.

Pensata per un client che fa polling

Ogni risposta porta un ETag. Ripetete la richiesta con If-None-Match e un orario invariato risponde 304 senza alcun corpo, che è il caso comune per uno schermo in un atrio che si aggiorna ogni pochi minuti. Un client ben educato trasferisce quasi nulla in un giorno tranquillo.

Le credenziali vengono scambiate una volta contro un token bearer che dura 24 ore e codifica le scuole che può leggere. Le applicazioni browser sono supportate tramite un elenco esplicito di origini consentite anziché un carattere jolly — indicateci l’origine da cui viene servita la vostra dashboard e verrà aggiunta.

La superficie precedente è ancora servita, e ancora congelata

Le istituzioni che si sono integrate con la API precedente non hanno visto la propria integrazione interrotta dalla v2. I percorsi legacy sono ancora serviti e sono congelati deliberatamente, e la v2 mantiene di proposito i nomi dei campi legacy — quindi passare alla v2 è un cambio di URL e non di parser, e i campi che la v2 aggiunge sono aggiunte e non sostituzioni.

È l’intera politica in una frase: una API su cui un’università costruisce è una promessa, e romperla per riordinare i nomi dei campi non è un risparmio.