API Pengembang

Dokumentasi API Peringkat Catur

Chess Rating API menyediakan akses terprogram ke mesin perhitungan Elo yang sama yang menggerakkan kalkulator di situs ini. Pengembang yang membangun alat manajemen klub, dasbor pelaporan turnamen, platform pelatihan, atau produk editorial dapat mengintegrasikan penghitungan peringkat langsung ke dalam alur kerja mereka tanpa menerapkan kembali logika rumus. Dokumentasi ini mencakup titik akhir yang tersedia, format permintaan dan respons, persyaratan autentikasi, dan pendekatan pembuatan versi yang menjaga integrasi tetap stabil. Anda dapat melanjutkan dengan Widget Peringkat Catur yang Dapat Disematkan untuk panduan terkait.

Titik Akhir Perhitungan yang Tersedia

API ini mendukung tiga alur kerja penghitungan utama: perubahan peringkat game tunggal (dengan dua peringkat, hasil, dan faktor K), pemrosesan batch (beberapa catatan game dalam satu permintaan), dan estimasi peringkat awal (dengan rata-rata peringkat lawan, skor, dan jumlah permainan). Setiap titik akhir mengembalikan keluaran terperinci yang sama seperti yang ditunjukkan pada halaman kalkulator, termasuk skor yang diharapkan, delta peringkat, dan proyeksi peringkat baru. Untuk detail implementasi dan validasi, tinjau metodologi.

Titik akhir mode turnamen menerima serangkaian peringkat dan hasil lawan, mengembalikan rincian per putaran dan total kumulatif. Semua respons menyertakan metadata tentang profil aturan mana yang diterapkan sehingga konsumen hilir dapat memverifikasi asumsi penghitungan.

Otentikasi dan Batas Nilai

Akses API memerlukan kunci API yang diteruskan sebagai token pembawa di header Otorisasi. Kunci tersedia dalam tingkat gratis dan premium. Tingkat gratis mengizinkan hingga 100 permintaan per hari dengan maksimal 10 game per permintaan batch. Kunci premium membuka throughput yang lebih tinggi, dukungan prioritas, dan akses ke titik akhir pemrosesan turnamen massal.

Batasan tarif diberlakukan per kunci, bukan per alamat IP. Melebihi batas akan mengembalikan status 429 dengan header Retry-After yang menunjukkan kapan jendela permintaan berikutnya terbuka. Semua batasan didokumentasikan dalam header respons dari setiap permintaan yang berhasil.

Profil Aturan dan Versi

Setiap respons API menyertakan bidang rule_profile yang menunjukkan kumpulan asumsi mana yang digunakan untuk penghitungan (misalnya, fide_2024, us_chess_current, generic_elo). Ketika peraturan federasi berubah, API menambahkan versi profil baru daripada mengubah yang sudah ada. Artinya, sistem downstream dapat menyematkan versi profil tertentu dan melakukan upgrade sesuai jadwalnya sendiri.

Perubahan yang dapat menyebabkan gangguan dikomunikasikan setidaknya 30 hari sebelumnya melalui log perubahan API dan milis pengembang. Penambahan yang tidak dapat terputus (bidang opsional baru, profil baru) diterapkan terus-menerus tanpa mengganggu integrasi yang sudah ada.

Format Respons dan Penanganan Kesalahan

Semua respons mengembalikan JSON dengan Tipe Konten: application/json. Perhitungan yang berhasil menghasilkan 200 dengan payload hasil penuh.
Kesalahan validasi (bidang yang hilang, peringkat di luar jangkauan, faktor K tidak valid) menghasilkan 422 dengan rangkaian kesalahan yang dapat dibaca manusia.
Kegagalan otentikasi menghasilkan 401. Kunci yang kedaluwarsa atau dicabut mengembalikan 403 dengan URL pengaktifan ulang.
Kesalahan server menampilkan 500 dengan ID permintaan untuk eskalasi dukungan. Semua respons kesalahan mengikuti struktur { error, message, request_id } yang sama.

Praktik Terbaik Integrasi

Cache penghitungan ulang secara lokal bila memungkinkan untuk meminimalkan panggilan API. Untuk alur kerja turnamen, gunakan titik akhir batch daripada membuat permintaan game tunggal berurutan. Selalu sertakan parameter rule_profile secara eksplisit daripada mengandalkan default server, sehingga integrasi Anda tetap deterministik bahkan ketika API menambahkan profil baru.

Untuk perangkat lunak klub dan dasbor pelatihan, pertimbangkan untuk menyimpan hasil penghitungan dan versi profil_aturan sehingga Anda dapat mengaudit atau menghitung ulang nanti jika peraturan federasi berubah. Hal ini sangat penting untuk alur kerja pelaporan resmi yang mengutamakan keakuratan riwayat.