Geliştirici API'si

Satranç Derecelendirme API Belgeleri

Satranç Derecelendirme API'si, bu sitedeki hesap makinelerine güç veren aynı Elo hesaplama motoruna programlı erişim sağlar. Kulüp yönetimi araçları, turnuva raporlama panoları, koçluk platformları veya editoryal ürünler geliştiren geliştiriciler, formül mantığını yeniden uygulamaya gerek kalmadan derecelendirme hesaplamalarını doğrudan iş akışlarına entegre edebilirler. Bu belge, mevcut uç noktaları, istek ve yanıt formatlarını, kimlik doğrulama gereksinimlerini ve entegrasyonları istikrarlı tutan sürüm oluşturma yaklaşımını kapsar. İlgili rehberlik için Yerleştirilebilir Satranç Derecelendirme Widget'ları ile devam edebilirsiniz.

Kullanılabilir Hesaplama Uç Noktaları

API üç temel hesaplama iş akışını destekler: tek oyun derecelendirme değişikliği (iki derecelendirme, bir sonuç ve bir K faktörü verildiğinde), toplu işleme (bir istekte birden fazla oyun kaydı) ve başlangıç derecelendirme tahmini (ortalama rakip derecelendirmesi, puan ve oyun sayısı göz önüne alındığında). Her uç nokta, beklenen puan, derecelendirme deltası ve öngörülen yeni derecelendirme dahil olmak üzere hesap makinesi sayfalarında gösterilen aynı ayrıntılı çıktıyı döndürür. Uygulama ve doğrulama ayrıntıları için metodolojiyi inceleyin.

Turnuva modu uç noktaları, sıralı bir rakip derecelendirmeleri ve sonuçları dizisini kabul ederek tur başına dökümleri ve kümülatif toplamları döndürür. Tüm yanıtlar, alt tüketicilerin hesaplama varsayımlarını doğrulayabilmesi için hangi kural profilinin uygulandığına ilişkin meta verileri içerir.

Kimlik Doğrulama ve Hız Sınırları

API erişimi, Yetkilendirme başlığında taşıyıcı belirteci olarak iletilen bir API anahtarı gerektirir. Anahtarlar ücretsiz ve premium katmanlarda mevcuttur. Ücretsiz katman, toplu istek başına en fazla 10 oyun olmak üzere günde en fazla 100 isteğe izin verir. Premium anahtarlar daha yüksek verimin, öncelikli desteğin ve toplu turnuva işleme uç noktalarına erişimin kilidini açar.

Hız sınırları IP adresi başına değil, anahtar başına uygulanır. Sınırın aşılması, bir sonraki istek penceresinin ne zaman açılacağını belirten Retry-After başlığını içeren bir 429 durumu döndürür. Tüm sınırlar, her başarılı isteğin yanıt başlıklarında belgelenir.

Kural Profilleri ve Sürüm Oluşturma

Her API yanıtı, hesaplama için hangi varsayım kümesinin kullanıldığını belirten bir Rules_profile alanı içerir (ör. fide_2024, us_chess_current, general_elo). Federasyon düzenlemeleri değiştiğinde API, mevcut profil sürümlerini değiştirmek yerine yeni bir profil sürümü ekler. Bu, aşağı akışlı sistemlerin belirli bir profil sürümüne sabitlenebileceği ve kendi programlarına göre yükseltilebileceği anlamına gelir.

Son değişiklikler, API değişiklik günlüğü ve geliştirici posta listesi aracılığıyla en az 30 gün önceden iletilir. Kesintisiz eklemeler (yeni isteğe bağlı alanlar, yeni profiller) mevcut entegrasyonları bozmadan sürekli olarak dağıtılır.

Yanıt Formatı ve Hata İşleme

Tüm yanıtlar Content-Type: application/json ile JSON'u döndürür. Başarılı hesaplamalar, tam sonuç yüküyle birlikte 200 değerini döndürür.
Doğrulama hataları (eksik alanlar, aralık dışı derecelendirmeler, geçersiz K faktörü), insan tarafından okunabilen bir hata dizisiyle 422 değerini döndürür.
Kimlik doğrulama hataları 401 değerini döndürür. Süresi dolmuş veya iptal edilen anahtarlar, yeniden etkinleştirme URL'siyle birlikte 403 değerini döndürür.
Sunucu hataları, destek yükseltmesi için istek kimliğiyle birlikte 500 değerini döndürür. Tüm hata yanıtları aynı { error, message, request_id } yapısını takip eder.

Entegrasyon İçin En İyi Uygulamalar

API çağrılarını en aza indirmek için tekrarlanan hesaplamaları mümkün olduğunca yerel olarak önbelleğe alın. Turnuva iş akışları için sıralı tek oyun istekleri yerine toplu uç noktayı kullanın. Sunucu varsayılanına güvenmek yerine her zaman Rules_profile parametresini açık bir şekilde ekleyin; böylece API yeni profiller eklediğinde bile entegrasyonunuz belirleyici kalır.

Kulüp yazılımı ve koçluk kontrol panelleri için, hem hesaplanan sonuçları hem de Rules_profile sürümünü saklamayı düşünün; böylece federasyon kuralları değişirse daha sonra denetleyebilir veya yeniden hesaplayabilirsiniz. Bu, özellikle tarihsel doğruluğun önemli olduğu resmi raporlama iş akışları için önemlidir.