API de développeur
Documentation de l'API d'évaluation des échecs
L'API Chess Rating fournit un accès programmatique au même moteur de calcul Elo qui alimente les calculatrices de ce site. Les développeurs qui créent des outils de gestion de club, des tableaux de bord de reporting de tournois, des plateformes de coaching ou des produits éditoriaux peuvent intégrer les calculs de notation directement dans leurs flux de travail sans réimplémenter la logique de la formule. Cette documentation couvre les points de terminaison disponibles, les formats de requête et de réponse, les exigences d'authentification et l'approche de gestion des versions qui maintient les intégrations stables. Vous pouvez poursuivre avec Widgets d'évaluation d'échecs intégrables pour une explication liée.
Points de terminaison de calcul disponibles
L'API prend en charge trois flux de calcul principaux : la modification de la note d'un seul jeu (en fonction de deux notes, d'un résultat et d'un facteur K), le traitement par lots (plusieurs enregistrements de jeu en une seule requête) et l'estimation de la note initiale (en fonction de la note moyenne de l'adversaire, du score et du nombre de parties). Chaque point de terminaison renvoie le même résultat détaillé que celui affiché sur les pages du calculateur, y compris le score attendu, le delta de note et la nouvelle note projetée. Pour les détails d’implémentation et de validation, consultez la méthodologie.
Les points de terminaison en mode tournoi acceptent un tableau ordonné de notes et de résultats des adversaires, renvoyant les répartitions par tour et les totaux cumulés. Toutes les réponses incluent des métadonnées sur le profil de règles appliqué afin que les consommateurs en aval puissent vérifier les hypothèses de calcul.
Authentification et limites de débit
L'accès à l'API nécessite une clé API transmise en tant que jeton de porteur dans l'en-tête Authorization. Les clés sont disponibles dans les niveaux gratuit et premium. Le niveau gratuit autorise jusqu'à 100 demandes par jour avec un maximum de 10 jeux par demande groupée. Les clés Premium débloquent un débit plus élevé, une prise en charge prioritaire et un accès aux points de terminaison de traitement groupé des tournois.
Les limites de débit sont appliquées par clé et non par adresse IP. Le dépassement de la limite renvoie un statut 429 avec un en-tête Retry-After indiquant quand la fenêtre de requête suivante s'ouvre. Toutes les limites sont documentées dans les en-têtes de réponse de chaque demande réussie.
Profils de règles et gestion des versions
Chaque réponse de l'API inclut un champ Rules_profile indiquant quel ensemble d'hypothèses a été utilisé pour le calcul (par exemple, fide_2024, us_chess_current, generic_elo). Lorsque les réglementations de la fédération changent, l'API ajoute une nouvelle version de profil plutôt que de modifier celles existantes. Cela signifie que les systèmes en aval peuvent épingler une version de profil spécifique et effectuer une mise à niveau selon leur propre calendrier.
Les modifications majeures sont communiquées au moins 30 jours à l'avance via le journal des modifications de l'API et la liste de diffusion des développeurs. Les ajouts ininterrompus (nouveaux champs optionnels, nouveaux profils) sont déployés en continu sans perturber les intégrations existantes.
Format de réponse et gestion des erreurs
- Toutes les réponses renvoient JSON avec Content-Type : application/json. Les calculs réussis renvoient 200 avec la charge utile complète du résultat.
- Les erreurs de validation (champs manquants, notes hors limites, facteur K invalide) renvoient 422 avec un tableau d'erreurs lisible par l'homme.
- Les échecs d'authentification renvoient 401. Les clés expirées ou révoquées renvoient 403 avec une URL de réactivation.
- Les erreurs du serveur renvoient 500 avec un ID de demande d'escalade de support. Toutes les réponses d'erreur suivent la même structure { error, message, request_id }.
Meilleures pratiques d'intégration
Mettez en cache les calculs répétés localement autant que possible pour minimiser les appels d’API. Pour les flux de travail des tournois, utilisez le point de terminaison par lots plutôt que de faire des requêtes séquentielles pour un seul jeu. Incluez toujours le paramètre Rules_profile explicitement plutôt que de vous fier à la valeur par défaut du serveur, afin que votre intégration reste déterministe même lorsque l'API ajoute de nouveaux profils.
Pour les logiciels de club et les tableaux de bord d'entraînement, pensez à stocker à la fois les résultats calculés et la version Rules_profile afin de pouvoir auditer ou recalculer plus tard si les règles de la fédération changent. Ceci est particulièrement important pour les flux de travail de reporting officiel où l’exactitude historique est importante.