Prawidłowe korzystanie z API: pamięć podręczna, hooki i limity żądań
PremiumIntegracja, która co minutę odpytuje Omniscol, czy dane uległy zmianie, w większości przypadków otrzymuje tę samą odpowiedź co przy poprzednim wywołaniu. Niepotrzebnie zużywa swój limit i obciąża serwer, nie uzyskując żadnej nowej informacji.
Na tej stronie opisano mechanizmy pozwalające uniknąć zbędnych wywołań oraz limity żądań obowiązujące w API.
Unikanie pobierania niezmienionych danych
Większość odpowiedzi API przy odczycie zawiera nagłówek ETag, który
identyfikuje wersję odpowiedzi. Należy zachować ten identyfikator razem
z otrzymanymi danymi i przesłać go przy kolejnym wywołaniu w nagłówku
If-None-Match:
curl -i -G "https://nazwa-szkoly.omniscol.com/api/schedules/lessons/20261102-20261108" \
-H "Authorization: Bearer $TOKEN" \
-H 'If-None-Match: W/"os1.…"'
Jeżeli dane nie uległy zmianie, Omniscol odpowiada 304 Not Modified bez
treści odpowiedzi. Można wówczas ponownie wykorzystać dane przechowywane
w pamięci podręcznej. W przeciwnym razie otrzymują Państwo pełną odpowiedź
200 OK z nowym ETag.
ETag jest wartością nieprzejrzystą: należy go zachować i odesłać w
niezmienionej postaci, łącznie z cudzysłowami i prefiksem W/, bez prób jego
konstruowania ani dekodowania. Jest on właściwy dla żądania, które go
wygenerowało, oraz dla użytego dostępu: nie wolno używać go dla innego adresu
URL ani z innym tokenem.
Nagłówek Cache-Control: private, no-cache oznacza, że odpowiedź może być
przechowywana w prywatnej pamięci podręcznej, ale przed ponownym użyciem musi
zostać zrewalidowana w Omniscol. Do tego właśnie służy If-None-Match.
Niektóre odpowiedzi nie zawierają ETag, w szczególności te, które zależą od bieżącej daty i mogą się zmieniać bez modyfikacji danych konta. Takie odpowiedzi należy pobierać ponownie przy każdym wywołaniu.
Po wdrożeniu nowej wersji Omniscol wszystkie ETag są odnawiane, nawet jeśli
dane się nie zmieniły. Pierwsze wywołanie otrzymuje wtedy odpowiedź 200,
a kolejne mogą znów korzystać z odpowiedzi 304.
304 zmniejsza również obciążenie po stronie serwera. W większości
przypadków, gdy od ostatniego wywołania żadne dane konta nie uległy zmianie,
Omniscol może odpowiedzieć bez ponownego odczytu danych, a taki 304 nie jest
wtedy wliczany do limitu przypisanego do klucza API. 304 uzyskany po
ponownym odczycie danych jest natomiast wliczany jak zwykła odpowiedź.
Regularna rewalidacja pozostaje więc tania, gdy dane są niezmienione. Nadal jednak podlega ogólnemu limitowi dla adresu IP.
Przechowywanie odpowiedzi w pamięci podręcznej
Jeżeli wielu użytkowników lub wiele ekranów Państwa aplikacji korzysta z tych samych danych, nie ma potrzeby odpytywać Omniscol dla każdego z nich.
Odpowiedzi i ich ETag należy przechowywać w pamięci podręcznej aplikacji,
nad którą mają Państwo kontrolę, na przykład w Redis, Memcached lub w tabeli
bazy danych. Aplikacja może wtedy udostępniać dane z tej pamięci, która
rewaliduje je w Omniscol za pomocą If-None-Match, w regularnych odstępach
czasu lub gdy hook zasygnalizuje zmianę.
Klucz pamięci podręcznej musi uwzględniać pełny adres URL, użyty token
uwierzytelniający oraz, jeśli Państwo z nich korzystają, treść żądania GET
i nagłówki, od których zależy odpowiedź, takie jak Accept-Language. Dwa
tokeny o różnych uprawnieniach mogą dawać dostęp do różnych danych: odpowiedź uzyskana za pomocą jednego z nich nie może nigdy
zostać udostępniona użytkownikowi, którego uprawnienia nie pozwalają na dostęp
do tych danych.
Razem z ETag należy też przechowywać treść każdej odpowiedzi. Bez
odpowiadających mu danych odpowiedź 304 nie pozwala odtworzyć oczekiwanego
wyniku.
Ta pamięć podręczna aplikacji różni się od współdzielonej pamięci podręcznej
HTTP: dyrektywa Cache-Control: private zabrania tej drugiej przechowywania
odpowiedzi.
Otrzymywanie powiadomień zamiast regularnego odpytywania
Zamiast okresowo sprawdzać, czy dane uległy zmianie, można poprosić Omniscol o powiadomienie aplikacji, gdy nastąpi modyfikacja.
Mechanizm ten opiera się na hookach, które konfiguruje się na ekranie personalizacji API (zob. Personalizacja API). Hook może obserwować konkretny punkt dostępu lub zdarzenie grupujące kilka zmian, na przykład modyfikację planu lekcji.
Unieważnianie pamięci podręcznej po otrzymaniu hooka
Najprostszy sposób polega na potraktowaniu hooka jako sygnału unieważnienia.
Gdy nadejdzie powiadomienie, aplikacja oznacza odpowiednie dane jako nieaktualne i rewaliduje je w Omniscol. Nie trzeba interpretować treści zmiany: hook wskazuje jedynie, że konieczne jest ponowne sprawdzenie.
To rozwiązanie naturalnie łączy się z opisaną wcześniej pamięcią podręczną.
Synchronizacja lekcji metodą różnicową
Jeżeli utrzymują Państwo zsynchronizowaną kopię lekcji, opcja Z danymi zdarzenia modyfikacji planu lekcji pozwala otrzymać różnicę zawierającą lekcje dodane, zmodyfikowane i usunięte.
Aplikacja może wtedy zastosować wyłącznie te zmiany, bez ponownego pobierania całego planu lekcji.
Zapewnienie odbioru powiadomień
Omniscol podejmuje tylko jedną próbę wysłania każdego hooka. Czeka najwyżej cztery sekundy, nie ponawia próby w razie niepowodzenia i odnotowuje je w swoich dziennikach.
Państwa serwer powinien więc szybko potwierdzić odbiór odpowiedzią 200 OK
lub 202 Accepted, a następnie wykonać niezbędne przetwarzanie
asynchronicznie.
Należy też zachować okresową rewalidację jako mechanizm nadrabiania zaległości.
Jeśli serwer był niedostępny w chwili wysłania hooka, to sprawdzenie pozwoli
wykryć pominięte zmiany. Dzięki odpowiedziom 304 jest ono tanie, gdy dane są
aktualne.
Zabezpieczanie hooków
Aby sprawdzić, że powiadomienie rzeczywiście pochodzi z Omniscol, należy skonfigurować niestandardowy nagłówek HTTP zawierający sekret znany wyłącznie Państwa aplikacji i Omniscol. Serwer powinien odrzucać wywołania, które nie zawierają oczekiwanej wartości.
Dwa dodatkowe nagłówki dostarczają informacji o kontekście powiadomienia:
X-Schoolidentyfikuje, którego konta Omniscol dotyczy powiadomienie;X-OS-authzawiera token uwierzytelniający użytkownika, który dokonał zmiany.
Token przesyłany w X-OS-auth jest poufny. Nie należy zapisywać go w
dziennikach, przekazywać innym usługom, a dostęp do niego trzeba ściśle
ograniczyć.
Żądanie wyłącznie niezbędnych danych
Odpowiedź zawierająca mniej danych jest zazwyczaj szybsza do wygenerowania, przesłania i zapisania w pamięci podręcznej.
W przypadku lekcji należy ograniczyć żądany okres i filtrować wyniki do interesujących jednostek (zob. API lekcji).
W przypadku wyszukiwania punkt dostępu search/query oferuje filtry,
projekcję pól i paginację (zob. Zaawansowane zapytania).
Aby zaktualizować dużą liczbę elementów tego samego rodzaju (klasy, sale, przedmioty itp.), zamiast mnożyć pojedyncze wywołania lepiej korzystać z punktów dostępu pozwalających przesłać całą kolekcję w jednym żądaniu, o ile są dostępne w dokumentacji OpenAPI.
Przestrzeganie limitów żądań
Do wywołań API stosowane są dwa limity żądań. Po osiągnięciu limitu Omniscol
odpowiada 429 Too Many Requests z nagłówkiem Retry-After, który wskazuje
liczbę sekund do odczekania przed ponowieniem żądania.
Limit dla adresu IP
Limit ogólny wynosi 300 żądań w oknie 10 sekund, łącznie dla wszystkich punktów dostępu API, w tym MCP i paneli informacyjnych.
Próg ten jest zazwyczaj wystarczający dla prawidłowo zaprojektowanej integracji. Może jednak zostać osiągnięty przez pętle wywołań bez opóźnień lub przez nadmierną liczbę żądań równoległych.
Limit dla klucza API
Tokeny pochodzące z tego samego klucza API współdzielą dwa limity:
- 60 żądań na minutę;
- 5 000 żądań na dobę.
Odpowiedzi mogą zawierać następujące nagłówki, które umożliwiają śledzenie zużycia:
RateLimit-Policywskazuje obowiązujące limity, na przykład60;w=60, 5000;w=86400;RateLimit-Limitwskazuje limit najbliższy wyczerpania;RateLimit-Remainingwskazuje liczbę żądań wciąż dostępnych w ramach tego limitu;RateLimit-Resetwskazuje liczbę sekund do jego odnowienia.
Nagłówków tych brakuje w szczególności w odpowiedziach 304 uzyskanych bez
ponownego odczytu danych: ich brak nie oznacza, że limit został wyczerpany.
Gdy limit zostanie wyczerpany, odpowiedź 429 podaje również czas oczekiwania
w swojej treści, w polu retry_after.
Odpowiedzi 304 uzyskane bez ponownego odczytu danych nie są wliczane do tych
limitów, ale nadal podlegają ogólnemu limitowi dla adresu IP.
Jeśli te limity utrudniają uzasadnione korzystanie z API, prosimy o kontakt zamiast mnożenia kluczy.
Obsługa błędów i ponawianie prób
Po odpowiedzi 429
Należy zachować czas wskazany w Retry-After przed ponowieniem żądania.
Natychmiastowe ponawianie jest bezcelowe i może przedłużyć problem, zwłaszcza
gdy kilka procesów aplikacji jednocześnie podejmuje kolejne próby.
Po błędzie serwera lub przekroczeniu czasu oczekiwania
Po błędzie 5xx lub przekroczeniu czasu oczekiwania żądanie odczytu można
ponowić ze wzrastającym odstępem między próbami: na przykład jedna sekunda,
potem dwie, potem cztery, aż do maksymalnej liczby prób.
W przypadku żądania zapisu sytuacja jest inna: modyfikacja mogła zostać zapisana, nawet jeśli odpowiedź nigdy do Państwa nie dotarła. Przed ponowieniem operacji należy sprawdzić rzeczywisty stan danych, aby uniknąć podwójnych modyfikacji.
Po odpowiedzi 401
Odpowiedzi 401 Unauthorized zazwyczaj nie da się rozwiązać ponowną próbą z
tym samym tokenem. Może ona oznaczać w szczególności, że token wygasł, że jego
klucz API został usunięty lub wygasł albo że żądany punkt dostępu nie należy
do tych, które klucz ten dopuszcza.
Przed ponowieniem wywołania należy sprawdzić token i powiązane z nim uprawnienia (zob. API Omniscol).