Dokumentacja API oceny szachowej

Interfejs API obsługuje trzy główne procesy obliczeń: zmianę klasyfikacji pojedynczej gry (biorąc pod uwagę dwie oceny, wynik i współczynnik K), przetwarzanie wsadowe (wiele rekordów gier w jednym żądaniu) i wstępne oszacowanie oceny (biorąc pod uwagę średnią ocenę przeciwnika, wynik i liczbę gier). Każdy punkt końcowy zwraca te same szczegółowe dane wyjściowe, które są widoczne na stronach kalkulatora, w tym oczekiwany wynik, różnicę oceny i przewidywaną nową ocenę. Szczegóły implementacji i walidacji znajdziesz w metodologię.

Punkty końcowe w trybie turniejowym akceptują uporządkowaną tablicę ocen i wyników przeciwników, wyświetlając zestawienia na rundy i skumulowane sumy. Wszystkie odpowiedzi zawierają metadane dotyczące tego, jaki profil reguł został zastosowany, aby dalsi konsumenci mogli zweryfikować założenia obliczeniowe.

Dostęp API wymaga klucza API przekazanego jako token nośnika w nagłówku Authorization. Klucze są dostępne w poziomach bezpłatnym i premium. Warstwa bezpłatna pozwala na maksymalnie 100 żądań dziennie, maksymalnie 10 gier na żądanie zbiorcze. Klucze premium odblokowują wyższą przepustowość, priorytetową obsługę i dostęp do punktów końcowych masowego przetwarzania turniejów.

Limity szybkości są egzekwowane dla każdego klucza, a nie dla adresu IP. Przekroczenie limitu powoduje zwrócenie stanu 429 z nagłówkiem Retry-After wskazującym, kiedy zostanie otwarte kolejne okno żądania. Wszystkie limity są udokumentowane w nagłówkach odpowiedzi każdego pomyślnego żądania.

Każda odpowiedź API zawiera pole Rules_profile wskazujące, jaki zestaw założeń został użyty do obliczeń (np. fide_2024, us_chess_current, rodzajowy_elo). Kiedy zmieniają się przepisy federacji, API dodaje nową wersję profilu zamiast modyfikować istniejące. Oznacza to, że systemy niższego szczebla mogą przypinać się do określonej wersji profilu i aktualizować według własnego harmonogramu.

Informacje o istotnych zmianach są przekazywane z co najmniej 30-dniowym wyprzedzeniem za pośrednictwem dziennika zmian API i listy mailingowej programistów. Nieprzerwane dodatki (nowe opcjonalne pola, nowe profile) są wdrażane w sposób ciągły, bez zakłócania istniejących integracji.

Jeśli to możliwe, buforuj powtarzane obliczenia lokalnie, aby zminimalizować wywołania API. W przypadku turniejów używaj wsadowego punktu końcowego zamiast wysyłać sekwencyjne żądania dotyczące pojedynczej gry. Zawsze dołączaj jawnie parametr Rules_profile, zamiast polegać na ustawieniach domyślnych serwera, dzięki czemu integracja pozostanie deterministyczna nawet wtedy, gdy interfejs API doda nowe profile.

W przypadku oprogramowania klubowego i pulpitów trenerskich rozważ przechowywanie zarówno obliczonych wyników, jak i wersji Rules_profile, aby móc później dokonać audytu lub ponownie obliczyć, jeśli zasady federacji ulegną zmianie. Jest to szczególnie ważne w przypadku oficjalnych procesów raportowania, w których liczy się dokładność historyczna.