Как устроен Omniscol — один API, один источник истины

Несколько особенностей устройства Omniscol стоит знать до того, как вы начнёте его интегрировать: они объясняют, почему API так полон, как интерфейс подстраивается под каждого пользователя, и на что следует обратить внимание в вопросах конфиденциальности.

Одно приложение на одном API

Omniscol работает как единое веб-приложение в вашем браузере. Каждый экран, кнопка и таблица строятся вызовами публичного API Omniscol — того же API, который можете вызывать и вы сами; он описан в интерактивном справочнике API Omniscol, на странице Developers (omniscol.com/fr/developers). За тем API, который вы интегрируете, нет никакого скрытого «настоящего» API: то, что использует интерфейс, и есть то, что получаете вы. Некоторые операции устроены наоборот — они предусмотрены для интеграции, но самим приложением не используются. Например, это точки доступа расширенного поиска и определения сущности (они предназначены для ИИ-агента через MCP) и те, которые позволяют внешней системе наполнять Omniscol (ETL, поддерживающий внешнюю базу в синхронном состоянии).

operationId — один ключ, один источник истины

Каждая операция — это пара «метод + URL» (например, GET /api/schedules/lessons/{datesrange}), и у каждой есть стабильный идентификатор — её operationId (здесь os_schedules_dates_get). Имя устроено по структуре: os (Omniscol), затем модуль (schedules), затем то, к чему относится операция (dates — иногда несколько сегментов, соединённых дефисами), и всегда последним — HTTP-метод (get, post, put, delete). Именно этот единый ключ Omniscol использует везде: чтобы назвать операцию на странице Developers, чтобы построить соответствующий инструмент MCP и чтобы обратиться к ней из переопределения или из этой справки. Он задан один раз, поэтому все поверхности остаются согласованными: документация, инструменты и интерфейс не могут разойтись, ведь все они читают одно и то же определение.

Интерфейс следует вашим правам

Графический элемент с действием — кнопка, вкладка, пункт меню — появляется, только когда лежащая в его основе операция доступна вам. Это зависит от вашей роли и от того, какие настраиваемые роли вам назначены (см. Пользователи и роли), а также от вашего тарифа и ваших опций (см. Тарифные планы и опции Omniscol). Измените любой из этих факторов — и интерфейс перестроится: элементы, а то и целые модули появятся или исчезнут.

Тот же принцип действует и за пределами ваших личных прав. ИТ-служба может отключить некоторые операции с помощью переопределения API, и соответствующие элементы исчезнут из интерфейса (см. Настройка API). То же происходит, когда данные поддерживаются внешней синхронизацией: их локальное создание и изменение могут быть отключены, и тогда их элементы управления уступают место синхронизации (см. Синхронизация с внешними системами).

Поэтому в Omniscol нет отдельного портала для учеников или преподавателей. Приложение одно; каждый видит интерфейс, согласованный с его собственными правами: ученик, преподаватель, администратор и обладатель настраиваемой роли получают ровно те операции, на которые имеют право, и ничего больше.

Интерфейс — это удобство, а не замок

Поскольку интерфейс управляется вашими правами, возникает соблазн считать скрытую кнопку границей безопасности. Это не так. Каждый вызов перепроверяется на сервере с учётом вашей личности и ваших прав; операция, на которую у вас нет права, там отклоняется, что бы ни показывал интерфейс. Интерфейс подстраивается ради ясности и удобства, а настоящая граница обеспечивается на стороне сервера, при каждом запросе.

Токены и ссылки общего доступа — одна модель

Токен API или ссылка общего доступа ограничены набором операций — теми, которые вы разрешаете при его создании. Сервер применяет это ограничение при каждом вызове, точно так же, как для вошедшего в систему пользователя. Ссылка общего доступа, токен и человек в интерфейсе — это три способа добраться до одного и того же API с контролем прав, и никогда — не чёрный ход в обход него.

Работа при обрыве соединения

Поскольку каждый экран читает данные через API, Omniscol может также хранить в вашем браузере уже полученные ответы, чтобы кратковременная потеря сети не прерывала чтение. Эта локальная копия находится в собственной базе данных (IndexedDB), рядом с обычным кэшем страниц браузера. Это кэш для чтения: если соединение пропадёт, вы продолжите видеть то, что уже открывали. Он не ставит ваши изменения в очередь и не воспроизводит их повторно — изменение всегда проходит через сервер.

Эта локальная копия создаётся только с вашего согласия. При первом использовании в браузере Omniscol спрашивает, доверяете ли вы ему; копия начинает создаваться после того, как вы согласились. Пункт Автономный кэш в меню пользователя затем в любой момент включает её или стирает; галочка показывает, что она включена.

Нужно знать две вещи:

• Персональные данные в неё не попадают. Сохраняются только успешные чтения; ответы, которые сервер помечает как не подлежащие хранению (данные сеанса и аутентификации), никогда не кэшируются, а из того, что кэшируется, программа удаляет контактные данные людей — e-mail, телефон, дату рождения, логин, идентификационный номер, состояние пароля — и полностью удаляет учётные записи администраторов. Локальная копия содержит обычные рабочие данные, а не именной справочник.
• На общем компьютере лучше использовать окно приватного просмотра. Выход из системы не стирает эту локальную копию (как и обычный кэш браузера); приватное окно удаляет обе при закрытии. Такой осторожности заслуживает любое веб-приложение на компьютере, который вы не контролируете.