المفاهيم
ترقيم الصفحات والتنسيقات
تُرقَّم القوائم باستخدام مؤشر (cursor). الاستجابات بتنسيق JSON مع اصطلاحات يمكن توقعها.
ترقيم الصفحات بالمؤشر#
تقبل كل نقطة نهاية تعيد قائمة معاملَي استعلام:
| المعامل | التفاصيل |
|---|---|
limit | عدد العناصر في الصفحة، من 1 إلى 100. القيمة الافتراضية: راجع نقطة النهاية في مرجع API. |
cursor | قيمة next_cursor من الصفحة السابقة. احذفه في الصفحة الأولى. |
للاستجابة دائمًا هذه البنية:
{
"data": [ { "id": "1043", "...": "..." } ],
"next_cursor": "eyJpZCI6IjEwNDMifQ"
}
عندما تكون قيمة next_cursor هي null فلا توجد صفحات أخرى. المؤشرات سلاسل نصية مُعتمة (opaque): لا تُنشئها ولا تعدّلها، ولا تخزّنها لمدة طويلة.
قراءة كل الصفحات#
curl "https://api.linework.app/open/v1/me/posts?limit=50" \
-H "Authorization: Bearer $LINEWORK_API_KEY"
# next page: pass the next_cursor you received
curl "https://api.linework.app/open/v1/me/posts?limit=50&cursor=eyJpZCI6IjEwNDMifQ" \
-H "Authorization: Bearer $LINEWORK_API_KEY"
async function* all(path) {
let cursor = null;
do {
const url = new URL(`https://api.linework.app/open/v1${path}`);
url.searchParams.set("limit", "100");
if (cursor) url.searchParams.set("cursor", cursor);
const res = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.LINEWORK_API_KEY}` },
});
const page = await res.json();
yield* page.data;
cursor = page.next_cursor;
} while (cursor);
}
for await (const post of all("/me/posts")) console.log(post.id);
import os, requests
API = "https://api.linework.app/open/v1"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['LINEWORK_API_KEY']}"
def all_items(path):
cursor = None
while True:
params = {"limit": 100}
if cursor:
params["cursor"] = cursor
page = s.get(API + path, params=params, timeout=30).json()
yield from page["data"]
cursor = page.get("next_cursor")
if not cursor:
break
for post in all_items("/me/posts"):
print(post["id"])
اصطلاحات JSON#
- أسماء الحقول بصيغة
camelCase(مثلًاcreatedAtوmediaIds). الاستثناء الوحيد هوnext_cursorفي استجابات القوائم. - المعرّفات سلاسل نصية، حتى عندما تبدو أرقامًا. لا تحوّلها إلى أرقام.
- التواريخ سلاسل نصية بتنسيق ISO 8601 بتوقيت UTC، مثلًا
2026-10-14T09:30:00.000Z. - أجسام الطلبات بتنسيق JSON (
Content-Type: application/json)، باستثناءPOST /mediaالذي يستخدمmultipart/form-data. - القيم الاختيارية المفقودة تكون
nullأو محذوفة، فتعامل مع الحالتين بالطريقة نفسها. - قد تُضاف حقول جديدة إلى الاستجابات في أي وقت: تجاهل الحقول التي لا تعرفها.
الإصدارات#
الإصدار موجود في المسار (/open/v1). ضمن v1 لا نجري إلا تغييرات متوافقة مع الإصدارات السابقة: نقاط نهاية جديدة، ومعاملات اختيارية جديدة، وحقول استجابة جديدة، ورموز أخطاء جديدة. أما التغييرات غير المتوافقة فستأتي في /open/v2، ويُعلَن عنها في سجل التغييرات قبل وقت كافٍ.