الترقيم

نظرة سريعة#

تعيد عملية القائمة صفحة واحدة في كل مرة. يسمّي الطلب الصفحة وحجمها، وتحمل الاستجابة الصفحة والإجمالي والروابط في الجسم، لا في ترويسة أبداً.

الأسماء pageNumber وpageSize وpage_number وpage_size وsize وlimit وoffset وcursor ليست أسماء الترقيم في المنصة. الواجهة التي تحتاج ترقيماً بمؤشر لمجموعة كبيرة جداً تذكر ذلك في وصفها وتظل تقدّم page وper_page.

الاستجابة#

{
  "data": [
    { "order_id": "ord_1042", "status": "shipped" },
    { "order_id": "ord_1043", "status": "open" }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 12,
    "per_page": 15,
    "total": 172
  },
  "links": {
    "first": "https://gate.api360.sa/<product-slug>/v1/orders?page=1&per_page=15",
    "next": "https://gate.api360.sa/<product-slug>/v1/orders?page=2&per_page=15",
    "prev": null,
    "last": "https://gate.api360.sa/<product-slug>/v1/orders?page=12&per_page=15"
  }
}

• data مصفوفة، فارغة حين لا تحمل الصفحة شيئاً. الصفحة التي تلي الأخيرة تُجاب بـ 200 مع data فارغة، لا بـ 404.
• meta.total عدد العناصر في المجموعة كلها. العميل الذي يحتاج العدد لا يقرأ ترويسة ولا يعدّ الصفحات.
• الواجهة التي تغلّف كل إجابة بـ success وmessage وdata، مثل واجهة وحدة التحكم في المنصة، تضع الصفحة مستوى أدنى: data.data وdata.meta. تقبل القاعدة الشكلين.

الحدود#

يُجاب عن per_page الأكبر من الحد الأقصى بـ 400 وبـغلاف الخطأ. فالتقليص الصامت يخفي الخطأ عن المستدعي. وكذلك page أو per_page الأقل من 1 يُجاب عنه بـ 400.

الحد الأقصى قيد أمان بقدر ما هو عقد: بدونه يستطيع المستدعي طلب الجدول كله في طلب واحد.

تتحقق منه#

انظر أيضاً#

• الأخطاء: الحالة 400 عند per_page غير الصالح.
• التسمية: sort_by وsort_dir بصيغة snake_case أيضاً.