API Pembangun

Dokumentasi API Penilaian Catur

API Penilaian Catur menyediakan akses terprogram kepada enjin pengiraan Elo yang sama yang menggerakkan kalkulator di tapak ini. Pembangun membina alatan pengurusan kelab, papan pemuka pelaporan kejohanan, platform bimbingan atau produk editorial boleh menyepadukan pengiraan penilaian terus ke dalam aliran kerja mereka tanpa melaksanakan semula logik formula. Dokumentasi ini meliputi titik akhir yang tersedia, format permintaan dan respons, keperluan pengesahan dan pendekatan versi yang memastikan integrasi stabil. Anda boleh teruskan dengan Widget Penilaian Catur Boleh Benam untuk panduan berkaitan.

Titik Akhir Pengiraan Tersedia

API menyokong tiga aliran kerja pengiraan utama: perubahan penilaian permainan tunggal (diberikan dua penilaian, keputusan dan faktor K), pemprosesan kelompok (rekod berbilang permainan dalam satu permintaan) dan anggaran penilaian awal (diberikan purata penilaian lawan, skor dan kiraan permainan). Setiap titik akhir mengembalikan output terperinci yang sama yang ditunjukkan pada halaman kalkulator, termasuk skor dijangka, delta penilaian dan penarafan baharu yang diunjurkan. Untuk butiran pelaksanaan dan pengesahan, semak metodologi.

Titik akhir mod kejohanan menerima susunan tersusun penilaian dan keputusan lawan, mengembalikan pecahan setiap pusingan dan jumlah terkumpul. Semua respons termasuk metadata tentang profil peraturan yang digunakan supaya pengguna hiliran boleh mengesahkan andaian pengiraan.

Pengesahan dan Had Kadar

Akses API memerlukan kunci API yang diluluskan sebagai token pembawa dalam pengepala Kebenaran. Kunci tersedia dalam peringkat percuma dan premium. Peringkat percuma membenarkan sehingga 100 permintaan setiap hari dengan maksimum 10 permainan setiap permintaan kelompok. Kekunci premium membuka kunci pemprosesan yang lebih tinggi, sokongan keutamaan dan akses kepada titik akhir pemprosesan kejohanan pukal.

Had kadar dikuatkuasakan setiap kunci, bukan setiap alamat IP. Melebihi had mengembalikan status 429 dengan pengepala Cuba Semula Selepas menunjukkan apabila tetingkap permintaan seterusnya dibuka. Semua had didokumenkan dalam pengepala respons setiap permintaan yang berjaya.

Profil Peraturan dan Versi

Setiap respons API termasuk medan rules_profile yang menunjukkan set andaian yang digunakan untuk pengiraan (mis., fide_2024, us_chess_current, generic_elo). Apabila peraturan persekutuan berubah, API menambah versi profil baharu dan bukannya mengubah suai yang sedia ada. Ini bermakna sistem hiliran boleh menyemat ke versi profil tertentu dan menaik taraf mengikut jadual mereka sendiri.

Perubahan pecah dimaklumkan sekurang-kurangnya 30 hari lebih awal melalui log perubahan API dan senarai mel pembangun. Penambahan tanpa putus (medan pilihan baharu, profil baharu) digunakan secara berterusan tanpa mengganggu penyepaduan sedia ada.

Format Respons dan Pengendalian Ralat

Semua respons mengembalikan JSON dengan Content-Type: application/json. Pengiraan yang berjaya mengembalikan 200 dengan muatan hasil penuh.
Ralat pengesahan (medan tiada, penilaian di luar julat, faktor K tidak sah) mengembalikan 422 dengan tatasusunan ralat yang boleh dibaca manusia.
Kegagalan pengesahan mengembalikan 401. Kekunci tamat tempoh atau dibatalkan mengembalikan 403 dengan URL pengaktifan semula.
Ralat pelayan mengembalikan 500 dengan ID permintaan untuk peningkatan sokongan. Semua respons ralat mengikut struktur { error, message, request_id } yang sama.

Amalan Terbaik Integrasi

Cache pengiraan berulang secara setempat apabila boleh untuk meminimumkan panggilan API. Untuk aliran kerja kejohanan, gunakan titik akhir kelompok dan bukannya membuat permintaan permainan tunggal yang berurutan. Sentiasa sertakan parameter rules_profile secara eksplisit dan bukannya bergantung pada lalai pelayan, jadi penyepaduan anda kekal deterministik walaupun apabila API menambah profil baharu.

Untuk perisian kelab dan papan pemuka kejurulatihan, pertimbangkan untuk menyimpan kedua-dua keputusan yang dikira dan versi rules_profile supaya anda boleh mengaudit atau mengira semula kemudian jika peraturan persekutuan berubah. Ini amat penting untuk aliran kerja pelaporan rasmi di mana ketepatan sejarah penting.