Jak działa Omniscol — jedno API, jedno źródło prawdy

Kilka faktów o tym, jak zbudowany jest Omniscol, warto poznać przed rozpoczęciem integracji — wyjaśniają, dlaczego API jest tak kompletne, w jaki sposób interfejs dostosowuje się do każdego użytkownika, oraz jeden punkt dotyczący poufności, o którym trzeba pamiętać.

Jedna aplikacja na jednym API

Omniscol działa jako jedna aplikacja internetowa w przeglądarce. Każdy ekran, każdy przycisk i każda tabela są rysowane przez wywołanie publicznego API Omniscol — tego samego API, które można wywołać samodzielnie, opisanego w interaktywnej dokumentacji API Omniscol, na stronie Programiści (omniscol.com/pl/developers). Nie ma żadnego ukrytego, „prawdziwego” API za tym, z którym prowadzi się integrację: to, czego używa interfejs, jest tym, co się otrzymuje. Kilka operacji działa w przeciwną stronę — udostępnionych do integracji, ale nieużywanych przez samą aplikację: na przykład punkty dostępu zaawansowanego wyszukiwania i rozpoznawania jednostek (przeznaczone dla agenta AI przez MCP) albo te, które pozwalają systemowi zewnętrznemu zasilać Omniscol danymi (ETL dbający o synchronizację zewnętrznej bazy).

operationId — jeden klucz, jedno źródło prawdy

Każda operacja to para metoda + URL (na przykład GET /api/schedules/lessons/{datesrange}) i każda nosi stabilny identyfikator: swój operationId (tutaj os_schedules_dates_get). Nazwa ma strukturę: os (Omniscol), następnie moduł (schedules), potem to, czego dotyczy operacja (dates — czasem kilka segmentów połączonych łącznikami), a na końcu zawsze metoda HTTP (get, post, put, delete). Tego jednego klucza Omniscol używa wszędzie — do nazwania operacji na stronie Programiści, do zbudowania odpowiadającego jej narzędzia MCP oraz do wskazania jej z poziomu nadpisania API lub z tej pomocy. Zdefiniowany tylko raz, utrzymuje spójność wszystkich powiązanych miejsc: dokumentacja, narzędzia i interfejs nie mogą się rozejść, ponieważ wszystkie czytają tę samą definicję.

Interfejs podąża za uprawnieniami

Element graficzny powiązany z działaniem — przycisk, zakładka, pozycja menu — pojawia się tylko wtedy, gdy stojąca za nim operacja jest dostępna dla użytkownika. Decydują o tym jego rola i role niestandardowe (zob. Użytkownicy i role), a także plan abonamentowy i opcje (zob. Plany i opcje Omniscol). Wystarczy zmienić jedno z nich, a interfejs składa się na nowo: pojedyncze elementy, a nawet całe moduły, pojawiają się lub znikają.

Ta sama zasada wykracza poza uprawnienia osobiste. Dział IT może wyłączyć niektóre operacje przez nadpisanie API, a odpowiadające im elementy znikają z interfejsu (zob. Personalizacja API). Tak samo jest wtedy, gdy jakieś dane są utrzymywane w aktualności przez synchronizację zewnętrzną: ich lokalne tworzenie i modyfikowanie mogą zostać wyłączone, a ich elementy sterujące ustępują wówczas miejsca synchronizacji (zob. Synchronizacja z systemami zewnętrznymi).

Dlatego Omniscol nie ma osobnego portalu dla uczniów ani dla nauczycieli. Istnieje jedna aplikacja; każdy widzi interfejs zsynchronizowany z własnymi uprawnieniami — uczeń, nauczyciel, administrator i posiadacz roli niestandardowej otrzymują dokładnie te operacje, do których mają prawo, i nic poza nimi.

Interfejs to wygoda, a nie zabezpieczenie

Ponieważ interfejsem sterują uprawnienia, łatwo byłoby wziąć ukryty przycisk za granicę bezpieczeństwa. Nią nie jest. Każde wywołanie jest ponownie sprawdzane na serwerze pod kątem tożsamości i uprawnień użytkownika; operacja, do której nie ma on prawa, zostaje tam odrzucona, niezależnie od tego, co pokazuje interfejs. Interfejs dostosowuje się dla przejrzystości i wygody; rzeczywista granica jest egzekwowana po stronie serwera, przy każdym żądaniu.

Tokeny i linki udostępniania, ten sam model

Token API albo link udostępniania jest ograniczony do zestawu operacji — tych, na które udzielono zgody przy jego tworzeniu. Serwer stosuje to ograniczenie przy każdym wywołaniu, dokładnie tak jak dla zalogowanego użytkownika. Link udostępniania, token i osoba pracująca w interfejsie to trzy sposoby dotarcia do tego samego API kontrolowanego uprawnieniami — nigdy furtka, która je omija.

Przetrwanie przerwy w połączeniu

Ponieważ każdy ekran czyta API, Omniscol może też zachowywać w przeglądarce już otrzymane odpowiedzi, aby krótka utrata sieci nie przerwała przeglądania. Ta kopia lokalna znajduje się we własnej bazie danych (IndexedDB), obok zwykłej pamięci podręcznej stron przeglądarki. To pamięć podręczna odczytu: jeśli połączenie zaniknie, nadal widać to, co zostało już otwarte. Nie kolejkuje ona modyfikacji ani ich nie odtwarza — modyfikacja zawsze przechodzi przez serwer.

Ta kopia lokalna opiera się na zgodzie użytkownika. Przy pierwszym użyciu danej przeglądarki Omniscol pyta, czy można mu zaufać; kopia zaczyna powstawać po wyrażeniu zgody. Pozycja Pamięć podręczna offline w menu użytkownika włącza ją lub czyści później w dowolnej chwili — znacznik wyboru wskazuje, że jest aktywna.

Dwie rzeczy, o których warto wiedzieć:

• Dane osobowe są z niej wyłączone. Zachowywane są tylko udane odczyty; odpowiedzi, które serwer oznacza jako niepodlegające przechowywaniu (dane sesji i uwierzytelniania), nigdy nie trafiają do pamięci podręcznej, a z tego, co trafia, oprogramowanie usuwa dane kontaktowe osób — e-mail, telefon, datę urodzenia, login, numer identyfikacyjny, stan hasła — oraz całkowicie usuwa konta administratorów. Kopia lokalna zawiera zwykłe dane robocze, a nie imienny spis osób.
• Na komputerze współdzielonym proszę raczej korzystać z okna przeglądania prywatnego. Wylogowanie nie usuwa tej kopii lokalnej (ani zwykłej pamięci podręcznej przeglądarki); okno prywatne usuwa obie przy zamknięciu. Na taką ostrożność zasługuje każda aplikacja internetowa na komputerze, nad którym użytkownik nie ma kontroli.