الاصطلاحات: الغلاف والفئات والترقيم والأخطاء

تعلّم هذه القواعد مرة واحدة وستتصرف كل نقطة نهاية كما تتوقع.

غلاف الاستجابة

كل استجابة ناجحة هي كائن JSON بمفتاحين:

المفتاح	المحتوى
data	كائن (مورد واحد) أو مصفوفة (قائمة)
meta	total وpage وsize وtotal_pages؛ تكون حقول الترقيم null عندما لا تدعم نقطة النهاية الترقيم

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

أسماء الحقول بصيغة snake_case في كل مكان (rider_number وtotal_points وseason_year).

الفئات: MotoGP وMoto2 وMoto3

تقبل نقاط النهاية المرتبطة بالموسم معامل الاستعلام category بإحدى القيم MOTOGP أو MOTO2 أو MOTO3. وclass اسم بديل بالقيم نفسها؛ أرسل أحدهما فقط وليس كليهما.

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

مرّر category صراحةً حتى لا تعتمد النتيجة على قيمة افتراضية.

الترقيم

نقاط النهاية التي تجلب «الكل»، وهي /riders و/teams و/races و/standings، مرقّمة بالمعاملين page (يبدأ من 1) وsize (من 1 إلى 200، والافتراضي 20):

GET /riders?page=2&size=50

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

كرّر الطلب حتى تصل page إلى total_pages:

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;
  }
}

أما القوائم المرتبطة بالموسم مثل /riders/seasons/{year} فتعيد الموسم كاملًا في استجابة واحدة.

الترتيب

يأتي الترتيب العام مرتبًا بحسب position. أما الروزنامة ونتائج السباقات فلا يُضمن ترتيبها، فرتّبها بنفسك:

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

المعرّفات

المورد	يُجلب بواسطة
السائق	رقم السباق: /riders/{rider_number} (مثل 93)
الفريق	معرّف معتم من أي قائمة فرق: /teams/{id}، أو بالاسم: /teams/name/{name}
السباق	الموسم + الجولة: /races/seasons/{year}/round/{round}، أو المعرّف المعتم: /races/{race_id}/results
الموسم	السنة: /seasons/{year}

خذ المعرّفات المعتمة ("82MQRdM5q7ub4OSm6Jhx") من استجابة القائمة بدلًا من كتابتها يدويًا، وطابق الفرق بالمعرّف لا بالاسم، فأسماء الرعاة تتغير من موسم إلى آخر.

أنواع الترتيب

إلى جانب المسارات المخصصة (/riders و/teams و/manufacturers و/bmw-m)، يمكنك طلب جدول الترتيب بحسب النوع:

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

الأنواع هي RIDER وTEAM وMANUFACTURER وBMW_M.

الأخطاء

تستخدم الأخطاء رموز حالة HTTP القياسية وهيئة JSON:

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

الحالة	المعنى	ما العمل
400	معامل غير صالح (سنة خاطئة أو فئة غير معروفة)	صحّح الطلب؛ تسرد validation_errors المشكلات عند وجودها
401 / 403	مفتاح RapidAPI مفقود أو غير صالح، أو لا يوجد اشتراك	تحقق من الترويستين ومن خطتك
404	السائق أو الفريق أو السباق أو الموسم غير موجود	اعرض حالة «غير موجود»
429	بلوغ حد المعدّل أو الحصة في خطتك	تمهّل وأعد المحاولة لاحقًا، أو رقِّ الخطة
5xx	مشكلة مؤقتة في الخادم	أعد المحاولة بتراجع أسّي؛ راجع صفحة الحالة

التخزين المؤقت

تتغير النتائج والترتيب بعد كل نهاية أسبوع سباق، وتتغير ملفات السائقين بين المواسم. خزّن مؤقتًا بسخاء لتوفير الحصة وإبقاء صفحاتك سريعة:

البيانات	مدة التخزين المقترحة
المواسم والسائقون والفرق والإحصاءات المهنية	24 ساعة
الروزنامة	12 ساعة
النتائج والترتيب	ساعة واحدة في نهايات أسابيع السباق، و12 ساعة في غيرها

أبقِ مفتاحك على الخادم

مفتاح RapidAPI هو بيانات اعتماد للفوترة. استدعِ الواجهة من خادمك الخلفي أو من دالة بلا خادم (serverless) أو من خطوة البناء، ولا تستدعها أبدًا من شيفرة متصفح أو تطبيق جوال تُرسل المفتاح إلى المستخدمين. يعرض دليل جدول الترتيب وسيطًا صغيرًا مع تخزين مؤقت.