تدعم جميع نقاط نهاية واجهة برمجة تطبيقات NueForm التي تُرجع قوائم موارد التصفح القائم على الصفحات. يغطي هذا الدليل معاملات الاستعلام وتنسيق الاستجابة وأنماط التكرار عبر جميع النتائج.
معاملات الاستعلام
تحكم في التصفح باستخدام معاملَي استعلام:
| المعامل | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
page | عدد صحيح | 1 | رقم الصفحة المطلوب استرداده (يبدأ من 1). |
per_page | عدد صحيح | 20 | عدد العناصر في كل صفحة. الحد الأدنى: 1، الحد الأقصى: 100. |
إذا تجاوز per_page القيمة 100، تقوم الواجهة البرمجية تلقائيًا بتحديده عند 100. القيم الأقل من 1 تُعاد افتراضيًا إلى 1.
مثال على الطلب
/api/v1/forms?page=2&per_page=25curl -X GET "https://app.nueform.com/api/v1/forms?page=2&per_page=25" \
-H "Authorization: Bearer nf_your_api_key_here"
تنسيق الاستجابة
تتضمن الاستجابات المُصفّحة كائن meta إلى جانب مصفوفة data:
{
"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
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
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)
لمجموعات البيانات الكبيرة، استخدم مولّدًا غير متزامن لمعالجة العناصر فور وصولها بدلاً من تحميل كل شيء في الذاكرة:
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:
{
"data": [],
"meta": {
"page": 1,
"per_page": 20,
"total": 0,
"total_pages": 0
}
}
صفحة تتجاوز الإجمالي
طلب رقم صفحة يتجاوز total_pages يُرجع مصفوفة data فارغة. تظل قيم meta تعكس المجموعة الكلية:
{
"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 لتحديد متى يجب التوقف. لا تكرر بشكل لا نهائي ولا تفترض عددًا ثابتًا من الصفحات.
أضف تأخيرًا بين الصفحات لمجموعات البيانات الكبيرة
إذا كنت تجلب صفحات كثيرة، أضف تأخيرًا صغيرًا بين الطلبات لتجنب الوصول إلى حدود الطلبات:
// Add a 200ms delay between page requests
await new Promise((resolve) => setTimeout(resolve, 200));
خزّن الإجمالي مؤقتًا عند الاقتضاء
إذا كنت تحتاج فقط إلى العدد الإجمالي (مثل عرض "47 نموذجًا")، اطلب per_page=1 واقرأ meta.total لتقليل نقل البيانات:
curl -X GET "https://app.nueform.com/api/v1/forms?per_page=1" \
-H "Authorization: Bearer nf_your_api_key_here"
تعكس نتائج التصفح حالة البيانات في وقت كل طلب. إذا تم إنشاء عناصر أو حذفها بين طلبات الصفحات، فقد ترى نسخًا مكررة أو تفوتك عناصر. للحصول على لقطات متسقة، اجلب جميع الصفحات بسرعة أو استخدم webhooks للحصول على تحديثات في الوقت الفعلي.