NueForm

التصفح بين الصفحات

تعرّف على كيفية التصفح عبر نقاط نهاية قوائم واجهة برمجة تطبيقات NueForm باستخدام التصفح القائم على الصفحات، بما في ذلك معاملات الاستعلام وبيانات الاستجابة الوصفية وأمثلة التكرار.

تدعم جميع نقاط نهاية واجهة برمجة تطبيقات NueForm التي تُرجع قوائم موارد التصفح القائم على الصفحات. يغطي هذا الدليل معاملات الاستعلام وتنسيق الاستجابة وأنماط التكرار عبر جميع النتائج.

معاملات الاستعلام

تحكم في التصفح باستخدام معاملَي استعلام:

المعاملالنوعالقيمة الافتراضيةالوصف
pageعدد صحيح1رقم الصفحة المطلوب استرداده (يبدأ من 1).
per_pageعدد صحيح20عدد العناصر في كل صفحة. الحد الأدنى: 1، الحد الأقصى: 100.

إذا تجاوز per_page القيمة 100، تقوم الواجهة البرمجية تلقائيًا بتحديده عند 100. القيم الأقل من 1 تُعاد افتراضيًا إلى 1.

مثال على الطلب

GET/api/v1/forms?page=2&per_page=25
curl
curl -X GET "https://app.nueform.com/api/v1/forms?page=2&per_page=25" \
  -H "Authorization: Bearer nf_your_api_key_here"

تنسيق الاستجابة

تتضمن الاستجابات المُصفّحة كائن meta إلى جانب مصفوفة data:

json
{
  "data": [
    {
      "id": "clx1abc2d3e4f5g6h7i8j9k0",
      "title": "Customer Feedback",
      "status": "published",
      "created_at": "2026-01-15T09:30:00.000Z"
    },
    {
      "id": "clx2def3g4h5i6j7k8l9m0n1",
      "title": "Employee Survey",
      "status": "draft",
      "created_at": "2026-01-20T14:00:00.000Z"
    }
  ],
  "meta": {
    "page": 2,
    "per_page": 25,
    "total": 73,
    "total_pages": 3
  }
}

حقول Meta

الحقلالنوعالوصف
pageعدد صحيحرقم الصفحة الحالية.
per_pageعدد صحيحعدد العناصر في كل صفحة (كما تم تطبيقه).
totalعدد صحيحالعدد الإجمالي للعناصر عبر جميع الصفحات.
total_pagesعدد صحيحالعدد الإجمالي للصفحات (يُحسب كـ ceil(total / per_page)).

التكرار عبر جميع الصفحات

عندما تحتاج إلى استرداد كل عنصر من نقطة نهاية قائمة، كرّر عبر الصفحات حتى يتجاوز page قيمة total_pages.

JavaScript

javascript
async function fetchAllForms() {
  const allForms = [];
  let page = 1;
  let totalPages = 1;

  do {
    const response = await fetch(
      `https://app.nueform.com/api/v1/forms?page=${page}&per_page=100`,
      {
        headers: {
          "Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
        },
      }
    );

    const { data, meta } = await response.json();
    allForms.push(...data);
    totalPages = meta.total_pages;
    page++;
  } while (page <= totalPages);

  console.log(`Fetched ${allForms.length} forms in total.`);
  return allForms;
}

Python

python
import os
import requests

API_KEY = os.environ["NUEFORM_API_KEY"]
BASE_URL = "https://app.nueform.com/api/v1"

def fetch_all_forms():
    all_forms = []
    page = 1
    total_pages = 1

    while page <= total_pages:
        response = requests.get(
            f"{BASE_URL}/forms",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"page": page, "per_page": 100},
        )
        body = response.json()
        all_forms.extend(body["data"])
        total_pages = body["meta"]["total_pages"]
        page += 1

    print(f"Fetched {len(all_forms)} forms in total.")
    return all_forms

مولّد غير متزامن (JavaScript)

لمجموعات البيانات الكبيرة، استخدم مولّدًا غير متزامن لمعالجة العناصر فور وصولها بدلاً من تحميل كل شيء في الذاكرة:

javascript
async function* paginatedForms(perPage = 100) {
  let page = 1;
  let totalPages = 1;

  do {
    const response = await fetch(
      `https://app.nueform.com/api/v1/forms?page=${page}&per_page=${perPage}`,
      {
        headers: {
          "Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
        },
      }
    );

    const { data, meta } = await response.json();
    totalPages = meta.total_pages;

    for (const form of data) {
      yield form;
    }

    page++;
  } while (page <= totalPages);
}

// Usage
for await (const form of paginatedForms()) {
  console.log(`Processing: ${form.title}`);
}

الحالات الحدية

نتائج فارغة

إذا لم تتطابق أي عناصر مع الاستعلام، تُرجع الواجهة البرمجية مصفوفة data فارغة مع total: 0:

json
{
  "data": [],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 0,
    "total_pages": 0
  }
}

صفحة تتجاوز الإجمالي

طلب رقم صفحة يتجاوز total_pages يُرجع مصفوفة data فارغة. تظل قيم meta تعكس المجموعة الكلية:

json
{
  "data": [],
  "meta": {
    "page": 10,
    "per_page": 20,
    "total": 73,
    "total_pages": 4
  }
}

معاملات غير صالحة

يتم التعامل مع معاملات التصفح غير الصالحة بشكل سلس:

المُدخلالسلوك
page=0 أو page=-1يُعاد افتراضيًا إلى 1
page=abcيُعاد افتراضيًا إلى 1
per_page=0 أو per_page=-5يُعاد افتراضيًا إلى 1
per_page=500يُحدّد عند 100
per_page=abcيُعاد افتراضيًا إلى 20

أفضل الممارسات

استخدم الحد الأقصى لـ per_page للاسترداد بالجملة

عند جلب جميع الموارد، اضبط per_page=100 لتقليل عدد استدعاءات API. كل استدعاء يُحتسب ضمن حد الطلبات الخاص بك.

تحقق من total_pages قبل التكرار

اقرأ دائمًا total_pages من كائن meta لتحديد متى يجب التوقف. لا تكرر بشكل لا نهائي ولا تفترض عددًا ثابتًا من الصفحات.

أضف تأخيرًا بين الصفحات لمجموعات البيانات الكبيرة

إذا كنت تجلب صفحات كثيرة، أضف تأخيرًا صغيرًا بين الطلبات لتجنب الوصول إلى حدود الطلبات:

javascript
// Add a 200ms delay between page requests
await new Promise((resolve) => setTimeout(resolve, 200));

خزّن الإجمالي مؤقتًا عند الاقتضاء

إذا كنت تحتاج فقط إلى العدد الإجمالي (مثل عرض "47 نموذجًا")، اطلب per_page=1 واقرأ meta.total لتقليل نقل البيانات:

curl
curl -X GET "https://app.nueform.com/api/v1/forms?per_page=1" \
  -H "Authorization: Bearer nf_your_api_key_here"

تعكس نتائج التصفح حالة البيانات في وقت كل طلب. إذا تم إنشاء عناصر أو حذفها بين طلبات الصفحات، فقد ترى نسخًا مكررة أو تفوتك عناصر. للحصول على لقطات متسقة، اجلب جميع الصفحات بسرعة أو استخدم webhooks للحصول على تحديثات في الوقت الفعلي.

آخر تحديث: 6 أبريل 2026