Entwickler-API

Dokumentation der Schachbewertungs-API

Die Chess Rating API bietet programmgesteuerten Zugriff auf dieselbe Elo-Berechnungs-Engine, die die Rechner auf dieser Website unterstützt. Entwickler, die Club-Management-Tools, Turnier-Reporting-Dashboards, Coaching-Plattformen oder redaktionelle Produkte entwickeln, können Bewertungsberechnungen direkt in ihre Arbeitsabläufe integrieren, ohne die Formellogik neu zu implementieren. Diese Dokumentation behandelt verfügbare Endpunkte, Anforderungs- und Antwortformate, Authentifizierungsanforderungen und den Versionierungsansatz, der die Stabilität der Integrationen gewährleistet. Für verwandte Hinweise können Sie mit Einbettbare Schachbewertungs-Widgets fortfahren.

Verfügbare Berechnungsendpunkte

Die API unterstützt drei primäre Berechnungsabläufe: Bewertungsänderung in einem einzelnen Spiel (bei zwei Bewertungen, einem Ergebnis und einem K-Faktor), Stapelverarbeitung (mehrere Spieldatensätze in einer Anfrage) und anfängliche Bewertungsschätzung (bei durchschnittlicher Gegnerbewertung, Punktestand und Spielanzahl). Jeder Endpunkt gibt die gleiche detaillierte Ausgabe zurück, die auf den Rechnerseiten angezeigt wird, einschließlich erwarteter Punktzahl, Bewertungsdelta und prognostizierter neuer Bewertung. Details zur Umsetzung und Validierung finden Sie in die Methodik.

Endpunkte im Turniermodus akzeptieren eine geordnete Reihe von Gegnerbewertungen und -ergebnissen und geben Aufschlüsselungen pro Runde und kumulative Gesamtwerte zurück. Alle Antworten enthalten Metadaten darüber, welches Regelprofil angewendet wurde, damit nachgeschaltete Verbraucher die Berechnungsannahmen überprüfen können.

Authentifizierung und Ratenbeschränkungen

Für den API-Zugriff ist ein API-Schlüssel erforderlich, der als Bearer-Token im Authorization-Header übergeben wird. Schlüssel sind in den kostenlosen und Premium-Stufen erhältlich. Die kostenlose Stufe ermöglicht bis zu 100 Anfragen pro Tag mit maximal 10 Spielen pro Batch-Anfrage. Premium-Schlüssel ermöglichen einen höheren Durchsatz, Prioritätsunterstützung und Zugriff auf Endpunkte für die Massenverarbeitung von Turnieren.

Ratenbegrenzungen werden pro Schlüssel und nicht pro IP-Adresse durchgesetzt. Bei Überschreitung des Grenzwerts wird der Status 429 mit einem Retry-After-Header zurückgegeben, der angibt, wann das nächste Anforderungsfenster geöffnet wird. Alle Grenzwerte werden in den Antwortheadern jeder erfolgreichen Anfrage dokumentiert.

Regelprofile und Versionierung

Jede API-Antwort enthält ein Feld „rules_profile“, das angibt, welche Annahmen für die Berechnung verwendet wurden (z. B. fide_2024, us_chess_current, generic_elo). Wenn sich die Verbandsbestimmungen ändern, fügt die API eine neue Profilversion hinzu, anstatt bestehende zu ändern. Dies bedeutet, dass nachgelagerte Systeme eine bestimmte Profilversion festlegen und nach eigenem Zeitplan aktualisieren können.

Wichtige Änderungen werden mindestens 30 Tage im Voraus über das API-Änderungsprotokoll und die Entwickler-Mailingliste kommuniziert. Nicht unterbrechende Ergänzungen (neue optionale Felder, neue Profile) werden kontinuierlich bereitgestellt, ohne bestehende Integrationen zu stören.

Antwortformat und Fehlerbehandlung

Alle Antworten geben JSON mit Content-Type: application/json zurück. Erfolgreiche Berechnungen geben 200 mit der vollständigen Ergebnisnutzlast zurück.
Validierungsfehler (fehlende Felder, Bewertungen außerhalb des Bereichs, ungültiger K-Faktor) geben 422 mit einem für Menschen lesbaren Fehlerarray zurück.
Authentifizierungsfehler geben 401 zurück. Abgelaufene oder widerrufene Schlüssel geben 403 mit einer Reaktivierungs-URL zurück.
Serverfehler geben 500 mit einer Anforderungs-ID für eine Support-Eskalation zurück. Alle Fehlerantworten folgen der gleichen Struktur {error, message, request_id}.

Best Practices für die Integration

Speichern Sie wiederholte Berechnungen nach Möglichkeit lokal zwischen, um API-Aufrufe zu minimieren. Verwenden Sie für Turnier-Workflows den Batch-Endpunkt, anstatt sequenzielle Einzelspielanfragen zu stellen. Schließen Sie den Parameter „rules_profile“ immer explizit ein, anstatt sich auf den Serverstandard zu verlassen, damit Ihre Integration auch dann deterministisch bleibt, wenn die API neue Profile hinzufügt.

Erwägen Sie bei Vereinssoftware und Coaching-Dashboards, sowohl die berechneten Ergebnisse als auch die Rules_Profile-Version zu speichern, damit Sie sie später prüfen oder neu berechnen können, wenn sich die Verbandsregeln ändern. Dies ist besonders wichtig für offizielle Berichtsabläufe, bei denen es auf historische Genauigkeit ankommt.