Wise Timetable REST API

Ni kan granska det redan nu

Tjänstebeskrivningen kräver inga inloggningsuppgifter, så den första frågan en utvecklare ställer kan besvaras på en rad.

GET https://wise-tt.com/api/v2/meta returnerar tjänstens namn, versionen och listan över de endpoints servern för närvarande tillhandahåller. Ingen token, inget konto, inget säljsamtal — öppna den i en webbläsare. Det är också det ärliga sättet att upptäcka allt som lagts till efter att manualen senast reviderades.

Integrationsmanualen publiceras i sin helhet, utan registrering, med varje endpoints parametrar, ett realistiskt exempelsvar för var och en och kompletta fungerande exempel i curl, Python, JavaScript och C. Vi publicerar den eftersom en integration som ser genomförbar ut på papperet men visar sig inte vara det är en betydligt dyrare upptäckt i månad tre.

Att läsa data kräver ett API-konto, utfärdat av oss och begränsat till de skolor det får läsa. Den delen är avsiktlig: ett schema anger vem som undervisar vad och vilka studenter som deltar.

Vad API:et exponerar

• Scheman, per studentgrupp, lärare, sal eller kurs — eller hela skolan på en gång
• Fullständig information om en enskild händelse, inklusive program-, årskurs-, gren- och grupphierarkin bakom varje grupp som deltar
• Gränserna för det publicerade läsåret, så att en klient kan hindra användaren från att navigera till veckor som inte kan innehålla data
• Helgdagar, så att en tom dag läses som en helgdag och inte som saknade data
• Aviseringar kopplade till en skola, en grupp, en kurs eller en lärare, avdubblade och returnerade som strukturerade objekt
• Kodlistor för program, grenar, grupper, lärare, salar och kurser — de id:n och etiketter en väljare byggs av
• Salskapacitet, salskod och skolans egen salspostlåda, där skolan har fyllt i dem
• Skolans ringschema, eftersom passlängderna inte är desamma överallt
• Skolans egna veckonummer, och skolans eget namn på en vecka där den har ett — ett veckonummer i den här produkten är inte kalenderårets ISO-vecka, och ingen klient ska någonsin räkna ut ett
• De bokningstyper en skola använder och de salar varje lärare får reservera, för en klient som erbjuder bokning och inte bara läsning
• Vad varje skola tillåter en klient att erbjuda, så att en väljare för bläddring per lärare döljs där lärares engagemang behandlas som konfidentiella
• Närvarolistor, där ett lärosäte tar närvaro via QR-kod — varje lektions lista hel, per datum för en första fyllning och därefter det som ändrats sedan förra anropet, för ett studieadministrativt system. Personuppgifter om studenter, så ett konto läser dem endast med en egen behörighet

Salsbokningar, gjorda av en person i stället för av ett konto

Bokning är den enda delen av API:et som inte alls tar ett integrationskonto, och skälet är värt att ange tydligt: en bokning görs av någon, och schemat registrerar vem. En medarbetare loggar in med sitt eget användarnamn och lösenord, får en token som anger en skola och gäller i åtta timmar, och skapar, ändrar och raderar bokningar som sig själv — vilket också är varför en inloggningsuppgift som kompilerats in i en publicerad app aldrig kan nå den här ytan.

Innan något skrivs kan en klient fråga om ett mönster är ledigt. GET /v2/free-busy expanderar varannan tisdag från mars till maj, 08:00–10:00, sal B-004 till verkliga datum och rapporterar, datum för datum, vad som redan är i vägen — och om det är salen, läraren eller gruppen. En krock avvisas med de krockande datumen bifogade i stället för med ett platt nej, tillsammans med de närmaste starttiderna och de andra salar som är lediga på alla dessa datum. En planerare som menar allvar kan ändå boka över krocken, och det registreras som ett medvetet beslut i stället för att döljas.

Hela ytan — att logga in en person, skolans bokningstyper, varje lärares lista över tillåtna salar, tillgänglighet och att skapa, ändra och radera en bokning — är kapitel 13 i manualen, med ett genomgånget exempel som löper från inloggning till en bokad sal.

Byggt för en klient som pollar

Varje svar bär en ETag. Upprepa förfrågan med If-None-Match så svarar ett oförändrat schema med 304 helt utan innehåll, vilket är det vanliga fallet för en skärm i en foajé som uppdateras var några minuter. En väluppfostrad klient överför nästan ingenting en lugn dag.

Inloggningsuppgifter byts en gång mot en bearer-token som gäller i 24 timmar och kodar de skolor den får läsa. Webbläsarapplikationer stöds via en uttrycklig tillåtelselista över ursprung i stället för ett jokertecken — berätta från vilket ursprung Er instrumentpanel serveras så läggs det till.

Den äldre ytan serveras fortfarande, och är fortfarande fryst

Lärosäten som integrerade mot det tidigare API:et fick inte sin integration bruten av v2. De äldre sökvägarna serveras fortfarande och är medvetet frysta, och v2 behåller de äldre fältnamnen med avsikt — så att gå över till v2 är en ändring av URL och inte av parser, och de fält v2 lägger till är tillägg och inte ersättningar.

Det är hela policyn i en mening: ett API som ett universitet bygger mot är ett löfte, och att bryta det för att städa upp fältnamn är ingen besparing.