La API REST de Wise Timetable

Puede inspeccionarla ahora mismo

La descripción del servicio no necesita credenciales, de modo que la primera pregunta de un desarrollador se responde en una línea.

GET https://wise-tt.com/api/v2/meta devuelve el nombre del servicio, la versión y la lista de endpoints que el servidor ofrece en ese momento. Sin token, sin cuenta, sin llamada comercial — ábralo en un navegador. También es la forma honesta de descubrir cualquier cosa añadida después de la última revisión del manual.

El manual de integración se publica completo y sin restricciones, con los parámetros de cada endpoint, una respuesta de ejemplo realista para cada uno y ejemplos completos y funcionales en curl, Python, JavaScript y C. Lo publicamos porque descubrir en el tercer mes que una integración que parecía viable sobre el papel no lo era es mucho más caro.

Leer datos sí requiere una cuenta de API, emitida por nosotros y limitada a los centros que puede leer. Es deliberado: un horario indica quién enseña qué y qué estudiantes asisten.

Qué expone la API

• Horarios, por grupo de estudiantes, docente, aula o curso — o de todo el centro a la vez
• Detalle completo de un solo evento, incluida la jerarquía de programa, año, rama y grupo detrás de cada grupo que asiste
• Los límites del año académico publicado, para que un cliente pueda impedir que el usuario navegue a semanas que no pueden tener datos
• Festivos, para que un día vacío se lea como festivo y no como datos que faltan
• Notificaciones asociadas a un centro, un grupo, un curso o un docente, sin duplicados y devueltas como objetos estructurados
• Listas de códigos de programas, ramas, grupos, docentes, aulas y cursos — los identificadores y etiquetas con los que se construye un selector
• Capacidad del aula, código del aula y buzón de correo propio del aula del centro, cuando el centro los ha completado
• El horario de timbres del centro, porque la duración de las franjas no es igual en todas partes
• Los números de semana propios del centro, y el nombre que el centro da a una semana cuando lo tiene — un número de semana en este producto no es la semana ISO del año natural, y ningún cliente debería calcularlo
• Los tipos de reserva que usa un centro y las aulas que cada docente puede reservar, para un cliente que ofrece reservar además de leer
• Lo que cada centro permite ofrecer a un cliente, de modo que un selector por docente se oculte donde la dedicación de los docentes se trata como confidencial
• Listas de asistencia, donde una institución toma la asistencia con código QR — la lista de cada lección completa, por fechas para una primera carga y luego solo lo que cambió desde la última llamada, para un sistema de información estudiantil. Son datos personales de estudiantes, por lo que una cuenta solo los lee con un permiso propio

Reservas de aulas, hechas por una persona y no por una cuenta

La reserva es la única parte de la API que no usa una cuenta de integración, y conviene explicar por qué: una reserva la hace alguien, y el horario registra quién. Un miembro del personal inicia sesión con su propio usuario y contraseña, recibe un token que nombra un solo centro y dura ocho horas, y crea, modifica y elimina reservas como sí mismo — lo que también explica por qué una credencial compilada en una aplicación publicada nunca puede llegar a esta superficie.

Antes de escribir nada, un cliente puede preguntar si un patrón está libre. GET /v2/free-busy expande cada segundo martes de marzo a mayo, 08:00–10:00, aula B-004 en fechas reales e informa, fecha por fecha, qué hay ya en el camino — y si es el aula, el docente o el grupo. Un conflicto se rechaza con las fechas en conflicto adjuntas y no con un simple no, junto con las horas de inicio más cercanas y las otras aulas libres en todas esas fechas. Un planificador que lo decida puede reservar igualmente sobre el conflicto, y queda registrado como una decisión deliberada y no oculto.

Toda la superficie — iniciar la sesión de una persona, los tipos de reserva del centro, la lista de aulas permitidas de cada docente, la disponibilidad, y crear, modificar y eliminar una reserva — está en el capítulo 13 del manual, con un ejemplo práctico que va desde el inicio de sesión hasta un aula reservada.

Pensada para un cliente que consulta periódicamente

Cada respuesta lleva un ETag. Repita la solicitud con If-None-Match y un horario sin cambios responde 304 sin cuerpo alguno, que es el caso habitual de una pantalla en un vestíbulo que se actualiza cada pocos minutos. Un cliente bien comportado transfiere casi nada en un día tranquilo.

Las credenciales se intercambian una vez por un token de portador que dura 24 horas y codifica los centros que puede leer. Las aplicaciones de navegador se admiten mediante una lista explícita de orígenes permitidos y no un comodín — indíquenos el origen desde el que se sirve su panel y se añade.

La superficie anterior sigue disponible, y sigue congelada

Las instituciones que se integraron con la API anterior no vieron rota su integración por la v2. Las rutas heredadas siguen disponibles y están congeladas deliberadamente, y la v2 conserva a propósito los nombres de campo heredados — de modo que pasar a la v2 es un cambio de URL y no de analizador, y los campos que añade la v2 son adiciones y no reemplazos.

Esa es toda la política en una frase: una API sobre la que una universidad construye es una promesa, y romperla para ordenar nombres de campo no es un ahorro.