A API REST do Wise Timetable

Pode inspecioná-la agora mesmo

A descrição do serviço não precisa de credenciais, pelo que a primeira pergunta que um programador faz tem resposta numa só linha.

GET https://wise-tt.com/api/v2/meta devolve o nome do serviço, a versão e a lista de pontos de acesso que o servidor está atualmente a servir. Sem token, sem conta, sem chamada comercial — abra-o num navegador. É também a forma honesta de descobrir tudo o que tenha sido acrescentado depois da última revisão do manual.

O manual de integração é publicado na íntegra, sem formulário, com os parâmetros de cada ponto de acesso, uma resposta de exemplo realista para cada um e exemplos completos e funcionais em curl, Python, JavaScript e C. Publicamo-lo porque uma integração que parece viável no papel e se revela inviável é uma descoberta muito mais cara no terceiro mês.

Ler dados exige de facto uma conta de API, emitida por nós e limitada às escolas que pode ler. Essa parte é deliberada: um horário indica quem leciona o quê e que estudantes o frequentam.

O que a API expõe

• Horários, por grupo de estudantes, docente, sala ou disciplina — ou a escola inteira de uma vez
• Detalhe completo de um único evento, incluindo a hierarquia de curso, ano, ramo e grupo por trás de cada grupo que o frequenta
• Os limites do ano letivo publicado, para que um cliente possa impedir o utilizador de navegar para semanas que não podem conter dados
• Feriados, para que um dia vazio seja lido como feriado e não como dados em falta
• Notificações associadas a uma escola, um grupo, uma disciplina ou um docente, sem duplicados e devolvidas como objetos estruturados
• Listas de códigos para cursos, ramos, grupos, docentes, salas e disciplinas — os identificadores e etiquetas a partir dos quais se constrói um seletor
• Capacidade da sala, código da sala e a caixa de correio da própria sala da escola, quando a escola os preencheu
• O horário de toques da escola, porque a duração dos períodos não é igual em todo o lado
• Os números de semana da própria escola e o nome que a escola dá a uma semana, quando o tem — um número de semana neste produto não é a semana ISO do ano civil, e nenhum cliente deve alguma vez calculá-lo
• Os tipos de reserva que uma escola utiliza e as salas que cada docente pode reservar, para um cliente que ofereça reservas além de leitura
• O que cada escola permite que um cliente ofereça, para que um seletor por docente fique oculto onde os compromissos dos docentes são tratados como confidenciais
• Listas de presenças, quando uma instituição regista presenças por código QR — a lista de cada aula completa, por datas para um primeiro preenchimento e depois o que mudou desde a última chamada, para um sistema de informação dos estudantes. Dados pessoais sobre estudantes, pelo que uma conta só os lê com uma permissão própria

Reservas de salas, feitas por uma pessoa e não por uma conta

A reserva é a única parte da API que não utiliza de todo uma conta de integração, e a razão merece ser dita com clareza: uma reserva é feita por alguém, e o horário regista quem. Um membro do pessoal inicia sessão com o seu próprio nome de utilizador e palavra-passe, recebe um token que identifica uma escola e dura oito horas, e cria, altera e elimina reservas em nome próprio — o que é também a razão por que uma credencial compilada numa aplicação publicada nunca pode chegar a esta superfície.

Antes de escrever o que quer que seja, um cliente pode perguntar se um padrão está livre. GET /v2/free-busy expande todas as terças-feiras alternadas de março a maio, 08:00–10:00, sala B-004 em datas reais e comunica, data a data, o que já está no caminho — e qual deles é: a sala, o docente ou o grupo. Um conflito é recusado com as datas em conflito anexadas e não com um simples não, juntamente com as horas de início mais próximas e as outras salas que estão livres em todas essas datas. Um planeador que o queira mesmo pode reservar por cima do conflito, e isso fica registado como uma decisão deliberada e não escondido.

Toda a superfície — iniciar a sessão de uma pessoa, os tipos de reserva da escola, a lista de salas permitidas de cada docente, a disponibilidade e criar, alterar e eliminar uma reserva — constitui o capítulo 13 do manual, com um exemplo prático que vai do início de sessão a uma sala reservada.

Concebida para um cliente que consulta periodicamente

Cada resposta traz um ETag. Repita o pedido com If-None-Match e um horário inalterado responde 304 sem corpo algum, que é o caso comum de um ecrã num átrio que se atualiza a cada poucos minutos. Um cliente bem comportado transfere quase nada num dia calmo.

As credenciais são trocadas uma vez por um token de portador que dura 24 horas e codifica as escolas que pode ler. As aplicações de navegador são suportadas através de uma lista explícita de origens permitidas e não de um caráter universal — diga-nos a origem a partir da qual o seu painel é servido e ela é acrescentada.

A superfície mais antiga continua a ser servida e continua congelada

As instituições que se integraram na API anterior não viram a sua integração quebrada pela v2. Os caminhos antigos continuam a ser servidos e estão deliberadamente congelados, e a v2 mantém de propósito os nomes de campos antigos — pelo que passar para a v2 é uma mudança de URL e não uma mudança de analisador, e os campos que a v2 acrescenta são adições e não substituições.

Esta é toda a política numa só frase: uma API sobre a qual uma universidade constrói é uma promessa, e quebrá-la para arrumar nomes de campos não é uma poupança.