وثائق API لتقييم الشطرنج

تدعم واجهة برمجة التطبيقات (API) ثلاثة مسارات عمل حسابية أساسية: تغيير تصنيف اللعبة الواحدة (بالنظر إلى تقييمين، ونتيجة، وعامل K)، ومعالجة الدفعات (سجلات ألعاب متعددة في طلب واحد)، وتقدير التصنيف الأولي (بالنظر إلى متوسط تقييم الخصم، والنتيجة، وعدد الألعاب). تقوم كل نقطة نهاية بإرجاع نفس المخرجات التفصيلية الموضحة على صفحات الآلة الحاسبة، بما في ذلك النتيجة المتوقعة ودلتا التصنيف والتقييم الجديد المتوقع. لتفاصيل التنفيذ والتحقق، راجع المنهجية.

تقبل نقاط النهاية في وضع البطولة مجموعة مرتبة من تقييمات الخصم ونتائجه، وإرجاع التقسيمات لكل جولة والإجماليات التراكمية. تشتمل جميع الاستجابات على بيانات تعريف حول ملف تعريف القواعد الذي تم تطبيقه حتى يتمكن المستهلكون النهائيون من التحقق من افتراضات الحساب.

يتطلب الوصول إلى واجهة برمجة التطبيقات (API) تمرير مفتاح API كرمز مميز لحامل في رأس التفويض. المفاتيح متوفرة في المستويات المجانية والمميزة. تسمح الطبقة المجانية بما يصل إلى 100 طلب يوميًا بحد أقصى 10 ألعاب لكل طلب دفعة. تفتح المفاتيح المميزة إنتاجية أعلى ودعمًا ذا أولوية وإمكانية الوصول إلى نقاط نهاية معالجة الدورات المجمعة.

يتم فرض حدود المعدل لكل مفتاح، وليس لكل عنوان IP. يؤدي تجاوز الحد إلى إرجاع الحالة 429 مع رأس إعادة المحاولة بعد الإشارة إلى وقت فتح نافذة الطلب التالية. يتم توثيق جميع الحدود في رؤوس الاستجابة لكل طلب ناجح.

تشتمل كل استجابة لواجهة برمجة التطبيقات (API) على حقل ملف تعريف القواعد الذي يشير إلى مجموعة الافتراضات التي تم استخدامها للحساب (على سبيل المثال، fide_2024، us_chess_current، generic_elo). عندما تتغير لوائح الاتحاد، تضيف واجهة برمجة التطبيقات (API) إصدارًا جديدًا للملف الشخصي بدلاً من تعديل الإصدارات الحالية. وهذا يعني أن الأنظمة النهائية يمكنها التثبيت على إصدار ملف تعريف محدد وترقيته وفقًا لجدولها الزمني الخاص.

يتم إرسال التغييرات العاجلة قبل 30 يومًا على الأقل من خلال سجل تغييرات واجهة برمجة التطبيقات والقائمة البريدية للمطورين. يتم نشر الإضافات غير المنفصلة (الحقول الاختيارية الجديدة وملفات التعريف الجديدة) بشكل مستمر دون تعطيل عمليات التكامل الحالية.

قم بتخزين العمليات الحسابية المتكررة محليًا كلما أمكن ذلك لتقليل استدعاءات واجهة برمجة التطبيقات (API). بالنسبة لسير عمل البطولة، استخدم نقطة النهاية المجمعة بدلاً من تقديم طلبات متسلسلة للعبة واحدة. قم دائمًا بتضمين معلمة ملف القواعد بشكل صريح بدلاً من الاعتماد على الإعداد الافتراضي للخادم، بحيث يظل التكامل الخاص بك محددًا حتى عندما تضيف واجهة برمجة التطبيقات ملفات تعريف جديدة.

بالنسبة لبرامج النادي ولوحات معلومات التدريب، فكر في تخزين كل من النتائج المحسوبة وإصدار ملف تعريف القواعد حتى تتمكن من التدقيق أو إعادة الحساب لاحقًا في حالة تغيير قواعد الاتحاد. وهذا مهم بشكل خاص بالنسبة لسير عمل التقارير الرسمية حيث تكون الدقة التاريخية مهمة.