Prawidłowe korzystanie z API: pamięć podręczna, hooki i limity żądań

Premium

Optymalizacja wywołań API Omniscol: używanie ETag, aby nie pobierać niezmienionych danych, przechowywanie odpowiedzi w pamięci podręcznej, otrzymywanie powiadomień o zmianach dzięki hookom oraz przestrzeganie limitów żądań dla adresu IP i klucza API.

Integracja, 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-School identyfikuje, którego konta Omniscol dotyczy powiadomienie;
  • X-OS-auth zawiera 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-Policy wskazuje obowiązujące limity, na przykład 60;w=60, 5000;w=86400;
  • RateLimit-Limit wskazuje limit najbliższy wyczerpania;
  • RateLimit-Remaining wskazuje liczbę żądań wciąż dostępnych w ramach tego limitu;
  • RateLimit-Reset wskazuje 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).

Zobacz także