Konventionen: Envelope, Kategorien, Paginierung und Fehler

Lernen Sie diese Regeln einmal, und jeder Endpunkt verhält sich wie erwartet.

Das Antwort-Envelope

Jede erfolgreiche Antwort ist ein JSON-Objekt mit zwei Schlüsseln:

Schlüssel	Inhalt
data	Ein Objekt (einzelne Ressource) oder ein Array (Liste)
meta	total, page, size, total_pages – die Paginierungsfelder sind null, wenn der Endpunkt nicht paginiert ist

{
  "data": { "year": 2026, "status": "ACTIVE" },
  "meta": { "total": 1, "page": null, "size": null, "total_pages": null }
}

Feldnamen sind durchgehend snake_case (rider_number, total_points, season_year).

Kategorien: MotoGP, Moto2 und Moto3

Saisonbezogene Endpunkte akzeptieren den Query-Parameter category mit einem der Werte MOTOGP, MOTO2 oder MOTO3. class ist ein Alias mit denselben Werten – senden Sie entweder den einen oder den anderen, nicht beide.

GET /standings/seasons/2026/riders?category=MOTO2
GET /races/seasons/2026?category=MOTO3

Übergeben Sie category immer explizit, damit das Ergebnis nie von einem Standardwert abhängt.

Paginierung

Die „Alle abrufen“-Endpunkte – /riders, /teams, /races und /standings – werden mit page (ab 1) und size (1–200, Standard 20) paginiert:

GET /riders?page=2&size=50

"meta": { "total": 118, "page": 2, "size": 50, "total_pages": 3 }

Laufen Sie in einer Schleife, bis page den Wert total_pages erreicht:

async function getAll(path) {
  const rows = [];
  for (let page = 1; ; page++) {
    const { data, meta } = await getEnvelope(`${path}?page=${page}&size=200`);
    rows.push(...data);
    if (!meta.total_pages || page >= meta.total_pages) return rows;
  }
}

Saisonbezogene Listen wie /riders/seasons/{year} liefern die ganze Saison in einer Antwort.

Sortierung

Wertungen kommen nach position sortiert zurück. Kalender und Rennergebnisse sind nicht garantiert sortiert – sortieren Sie sie selbst:

races.sort((a, b) => a.round_number - b.round_number);
results.sort((a, b) => a.position - b.position);

Kennungen

Ressource	Abruf über
Fahrer	Startnummer: /riders/{rider_number} (z. B. 93)
Team	Opake ID aus einer beliebigen Teamliste: /teams/{id}, oder per Name: /teams/name/{name}
Rennen	Saison + Runde: /races/seasons/{year}/round/{round}, oder opake ID: /races/{race_id}/results
Saison	Jahr: /seasons/{year}

Übernehmen Sie opake IDs ("82MQRdM5q7ub4OSm6Jhx") aus einer Listenantwort, statt sie fest zu codieren, und ordnen Sie Teams über die ID statt über den Namen zu – Sponsorennamen ändern sich von Saison zu Saison.

Wertungstypen

Neben den dedizierten Routen (/riders, /teams, /manufacturers, /bmw-m) können Sie eine Wertungstabelle auch nach Typ anfordern:

GET /standings/seasons/2026/type/MANUFACTURER?category=MOTOGP

Die Typen sind RIDER, TEAM, MANUFACTURER und BMW_M.

Fehler

Fehler verwenden Standard-HTTP-Statuscodes und einen JSON-Body:

{
  "timestamp": "2026-01-27T19:18:29",
  "status": 404,
  "error": "Not Found",
  "message": "Rider not found with number: 99",
  "path": "/riders/99"
}

Status	Bedeutung	Was zu tun ist
400	Ungültiger Parameter (falsches Jahr, unbekannte Kategorie)	Anfrage korrigieren; validation_errors listet die Probleme auf, falls vorhanden
401 / 403	Fehlender oder ungültiger RapidAPI-Schlüssel oder kein Abonnement	Beide Header und Ihren Tarif prüfen
404	Der Fahrer, das Team, das Rennen oder die Saison existiert nicht	Einen „nicht gefunden“-Zustand anzeigen
429	Ratenlimit oder Kontingent Ihres Tarifs erreicht	Später erneut versuchen oder den Tarif wechseln
5xx	Vorübergehendes Serverproblem	Mit exponentiellem Backoff wiederholen; die Statusseite prüfen

Caching

Ergebnisse und Wertungen ändern sich nach jedem Rennwochenende, Profile zwischen den Saisons. Cachen Sie großzügig, um Kontingent zu sparen und Seiten schnell zu halten:

Daten	Empfohlene Cache-Dauer
Saisons, Fahrer, Teams, Karrierestatistiken	24 Stunden
Kalender	12 Stunden
Ergebnisse und Wertungen	1 Stunde an Rennwochenenden, sonst 12 Stunden

Schlüssel auf dem Server halten

Ihr RapidAPI-Schlüssel ist ein Abrechnungsmerkmal. Rufen Sie die API aus Ihrem Backend, einer Serverless-Funktion oder einem Build-Schritt auf – niemals aus Browser- oder Mobilcode, der den Schlüssel an Nutzer ausliefert. Die Anleitung zur Wertungstabelle zeigt einen kleinen Proxy mit Caching.