واجهة REST

الحزم غلاف رقيق فوق واجهة HTTP عادية. لو لغتك ليست TypeScript ولا PHP، نادِ المسارات مباشرة — نفس العقد بالضبط.

العنوان الأساسي والمصادقة

المفتاح يسافر في ترويسة، لا في سلسلة الاستعلام أبداً — سلاسل الاستعلام تُكتب في سجلات nginx وترويسات Referer.

bash

curl https://mygurb.com/api/sdk/community \
  -H "X-Api-Key: gurb_a1b2c3d4e5f6_..." \
  -H "Accept: application/json"

لا تضف لاحقة للعنوان الأساسي

العميل يضيف api/ بنفسه. تمرير عنوان ينتهي بـ /api/v1 ينتج طلبات لمسارات غير موجودة — وبحسب القاعدة أعلاه ترد 400 أو 401 لا 404.

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

الردود الناجحة ملفوفة في success/data. الحزم تفك الغلاف نيابةً عنك؛ لو ناديت المسار مباشرة فاقرأ data.

json

{ "success": true, "data": { "id": "cmt_1", "slug": "book-club" } }

الترقيم

كل مسار list يقبل page وlimit ويرد بالشكل نفسه.

json

GET /api/sdk/tweets?page=2&limit=20

{ "success": true, "data": {
    "items": [ … ],
    "page": 2, "limit": 20, "total": 143, "hasMore": true
} }

مسار مكتوب خطأ يرد 400 أو 401 — لا 404

ستة راوترات مركّبة على الجذر في هذا الباك إند تبتلع أي طلب غير مطابق قبل أن يستنتج Express «لا يوجد مسار». فخطأ مطبعي في الرابط يبدو تماماً كفشل مصادقة، ويرسلك تدقّق مفتاحاً لم يكن المشكلة أصلاً. تأكد من وجود المسار قبل أن تشخّص 400 أو 401.

bash

curl https://mygurb.com/api/totally/bogus/path
# → 400 {"error":"Tenant context required"}   ← not a 404, and not an auth problem

المسارات

الفعل	المسار	ما يقابلها في الحزمة
GET	/api/sdk/community	community.get()
GET	/api/sdk/community/settings	community.getSettings()
PATCH	/api/sdk/community/settings	community.updateSettings()
PATCH	/api/sdk/community/branding	community.updateBranding()
GET	/api/sdk/tweets	tweets.list()
POST	/api/sdk/tweets	tweets.create()
PATCH	/api/sdk/tweets/:id	tweets.update()
DELETE	/api/sdk/tweets/:id	tweets.delete()
GET	/api/sdk/tasks	tasks.list()
GET	/api/sdk/tasks/:id	tasks.get()
GET	/api/sdk/:parent/:id/comments	comments.list()
POST	/api/sdk/:parent/:id/comments	comments.create()
POST	/api/sdk/:parent/:id/like	likes.like()
GET	/api/sdk/members	members.list()
PATCH	/api/sdk/members/:id/role	members.setRole()
POST	/api/sdk/members/bulk	members.bulkUpsert()
PUT	/api/sdk/customization/sidebar	sidebar.update()
GET	/api/sdk/customization/advertisements/active	advertisements.listActive()
POST	/api/embed/sessions	embed.createSession()
GET	/api/admin/sdk/me	admin.me()
POST	/api/admin/sdk/communities	admin.communities.create()
POST	/api/admin/sdk/api-keys	admin.apiKeys.create()

/developers/reference