واجهة REST API لتطبيقك ومستنداتها

أحيانًا تحتاج برامج أخرى إلى بيانات تطبيقك: موقع شريك يعرض منتجاتك، أو جدول بيانات يجلب الطلبات الجديدة، أو تطبيق للهاتف، أو أداة أتمتة مثل Zapier أو n8n. تتواصل هذه البرامج مع تطبيقك عبر واجهة API: مجموعة من عناوين الويب (نقاط النهاية) تجيب ببيانات بدلًا من صفحات. وREST API هي النوع الأكثر شيوعًا.

ينشئ MonstarX واجهة من هذا النوع لك دون شفرة. تختار ما تريد مشاركته، فيصبح متاحًا خلال ثوانٍ، مع صفحة مرجعية يقرؤها المطوّرون.

أين أجدها؟

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

كيف أنشئ نقطة نهاية؟

1. في الإدارة›APIs، انقر على نقطة نهاية جديدة (أو على + بجانب نقاط النهاية).

2. في حقل المجموعة، اختر الجدول الذي تعمل عليه نقطة النهاية، مثل Recipes.

3. في حقل العملية، اختر ما تفعله نقطة النهاية:

   العملية	الطريقة والعنوان	ما تفعله
   عرض القائمة	GET /recipes	تعيد السجلات، صفحة في كل مرة.
   جلب	GET /recipes/{id}	تعيد سجلًا واحدًا بمعرّفه.
   إنشاء	POST /recipes	تضيف سجلًا.
   تحديث	PATCH /recipes/{id}	تغيّر بعض حقول السجل.
   حذف	DELETE /recipes/{id}	تزيل سجلًا.

4. أعطها الاسم ومسار URL، وإن شئت الوصف. تظهر هذه في مستندات API.

5. في الحقول المتاحة، حدد بالضبط الحقول التي يحق للمستدعين رؤيتها أو إرسالها. وكل حقل غير محدد يبقى خاصًا. أما الحقول التي تبدو حساسة، ككلمات المرور والرموز، فتُستبعد دائمًا.

6. في قسم الوصول، اختر من يحق له استدعاؤها (راجع ما يلي).

7. حدد نشر نقطة النهاية وانقر على حفظ ونشر نقطة النهاية. نقطة النهاية المنشورة متاحة، أي تجيب عن الطلبات فورًا. وإن تركت المربع دون تحديد، فإن حفظ نقطة النهاية يبقيها مسودة.

   

في القائمة، تظهر على كل نقطة نهاية علامة متاحة أو مسودة. وتظهر الكلمة نفسها تحت تعديل نقطة النهاية، تتبعها التغييرات غير المحفوظة إلى أن تحفظ. ألغِ تحديد نشر نقطة النهاية واحفظ لإيقاف نقطة النهاية دون حذفها، أما حذف فيزيلها.

ملاحظة

عمليات إنشاء وتحديث وحذف تغيّر بياناتك الحقيقية. قبل أن تتمكن من نشر إحداها، فعّل ذلك الإجراء (الإضافة أو التعديل أو الحذف) للجدول في إعداداته في تبويب الإدارة. راجع لوحة إدارة تطبيقك.

من يستطيع استدعاء نقاط النهاية الخاصة بي؟

الوصول	من يستطيع الاستدعاء	متاح لـ
قراءة عامة	أي شخص لديه العنوان.	عرض القائمة وجلب فقط
مفتاح API للمشروع	من يرسل أحد مفاتيح API الخاصة بمشروعك فقط.	كل العمليات

نقاط النهاية التي تغيّر البيانات تحتاج دائمًا إلى مفتاح.

كيف أنشئ مفتاح API؟

1. في الإدارة›APIs، انقر على مفاتيح API.

2. اكتب اسمًا يوضح مكان استخدام المفتاح، مثل «خادم أداة الوصفات»، وانقر على إنشاء مفتاح.

3. انسخ المفتاح فورًا، فهو يبدأ بـ mxapi_ ولا يمكن عرضه مجددًا. احفظه في مكان آمن، كمدير كلمات المرور أو أسرار الخدمة الأخرى.

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

يرسل المستدعون المفتاح في ترويسة Authorization: Authorization: Bearer mxapi_….

تنبيه

أبقِ مفاتيح API على خادم. المفتاح الموضوع في صفحة ويب أو تطبيق هاتف يستطيع قراءته أي شخص يبحث عنه.

كيف أجرّب نقطة نهاية؟

افتح نقطة النهاية وانقر على اختبار. أدخل معرّف السجل أو مفتاح Bearer أو محتوى الطلب JSON إن كانت نقطة النهاية تحتاج إليها، وانقر على إرسال الطلب. ترى الحالة (200 تعني أنها نجحت) والمدة التي استغرقتها والإجابة. ولنقطة نهاية تحتاج إلى مفتاح، الصق أحد مفاتيحك من مفاتيح API في مفتاح Bearer.

تذهب الاختبارات إلى نقطة النهاية الحقيقية المتاحة، لذا:

• لا يمكن اختبار المسودة بعد. يقول تبويب الاختبار نقطة النهاية هذه ما زالت مسودة، فانقر هناك على حفظ ونشر نقطة النهاية لنشرها واختبارها.
• احفظ تغييراتك أولًا. إذا كانت هناك تغييرات غير محفوظة، يطلب منك تبويب الاختبار الحفظ قبل الاختبار، مع زر حفظ نقطة النهاية.

اختبار إنشاء أو تحديث أو حذف يغيّر بياناتك الحقيقية.

وفي تبويب الشفرة أمر cURL جاهز للنسخ، وملف OpenAPI JSON الذي تستطيع أدوات API مثل Postman وInsomnia استيراده.

كيف أنشر مستندات API وأشاركها؟

مستندات API هي صفحة مرجع API للمطوّرين: كل نقطة نهاية متاحة، وحقولها، وهل تحتاج إلى مفتاح، ومربع جرّبه، ومثال cURL. نشر نقطة النهاية لا ينشر المستندات، فأنت من يختار متى يشاركها.

1. انشر نقطة نهاية واحدة على الأقل، واحفظ أي تغييرات. إلى أن تفعل ذلك، يعرض شريط مرجع API أعلى الإدارة›APIs العلامة غير منشورة ويخبرك بما ينقص.

2. انقر على نشر المستندات.

   

3. يعرض الشريط الآن منشورة. انقر على نسخ رابط المستندات لمشاركة العنوان، أو على فتح مستندات API تحت مفاتيح API لترى الصفحة. يبدو العنوان هكذا: https://monstarx.com/api-docs/<your project id>.

monstarx.com

تبدأ الصفحة باسم مشروعك ووصفه، وعدد نقاط النهاية التي تعرضها، ومعرّف المشروع، والعنوان الأساسي. يستطيع أي شخص لديه الرابط قراءتها، ويُطلب من محركات البحث عدم فهرستها. لا تعرض إلا نقاط النهاية المتاحة، ولا تعرض المفاتيح أبدًا. ورابط OpenAPI JSON في الأعلى يقود إلى الوصف نفسه كملف.

لإيقاف المستندات، انقر على إلغاء نشر المستندات: تتوقف الصفحة وملف OpenAPI عن العمل، بينما تواصل نقاط النهاية الإجابة. وإذا أوقفت كل نقاط النهاية، يُلغى نشر المستندات أيضًا، وتنشرها مجددًا حين تكون جاهزًا.

كيف تبدو الطلبات والإجابات؟

تقع كل نقطة نهاية تحت https://monstarx.com/api/rest/<your project id>، يليه مسارها.

عرض القائمة

curl 'https://monstarx.com/api/rest/<project id>/recipes?page=1&limit=25'

{
  "data": [
    { "id": "41a6…", "title": "Street tacos al pastor", "country_code": "MX" }
  ],
  "page": 1,
  "limit": 25,
  "hasMore": false
}

قيمة limit من 1 إلى 100 سجل في الصفحة (25 إن لم تحددها)، وقيمة page من 1 إلى 100. وتوضح hasMore هل توجد صفحة أخرى.

إنشاء

curl -X POST 'https://monstarx.com/api/rest/<project id>/recipes' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Lemon ricotta pancakes", "country_code": "IT"}'

تتضمن الإجابة (بالحالة 201) السجل الجديد تحت data ومعرّفه id.

التحديث والحذف

curl -X PATCH 'https://monstarx.com/api/rest/<project id>/recipes/RECORD_ID' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Fluffy lemon ricotta pancakes"}'

curl -X DELETE 'https://monstarx.com/api/rest/<project id>/recipes/RECORD_ID' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY'

تجيب تحديث بالسجل بعد تغييره، وتجيب حذف بـ { "deleted": true }.

قواعد ما ترسله:

• كائن JSON مع Content-Type: application/json، بحجم أقصاه 64 KB.
• الحقول المتاحة فقط، وكل منها قيمة بسيطة: نص (حتى 20000 حرف)، أو رقم، أو true/false، أو null.
• لا يمكن تعيين المعرّف أو تغييره، ولا الحقول المخصصة للقراءة فقط في الإدارة.

عندما يكون هناك خطأ، تتضمن الإجابة رسالة error وحالة: 400 (الطلب غير صحيح)، و401 (يلزم مفتاح API صالح للمشروع)، و403 (ذلك الجدول أو الإجراء غير مسموح به في الإدارة)، و404 (لا توجد نقطة نهاية أو سجل بهذا الشكل)، و409 (تعارض، كالتكرار)، و413 (الإجابة ستتجاوز 1 MB، فأتح حقولًا أقل أو استخدم صفحة أصغر).

الأسئلة الشائعة

لماذا لا أستطيع النقر على «نشر المستندات»؟

تحتاج المستندات إلى نقطة نهاية متاحة واحدة على الأقل ودون تغييرات غير محفوظة. حدد نشر نقطة النهاية في إحدى نقاط النهاية، وانقر على حفظ ونشر نقطة النهاية، ثم على نشر المستندات.

هل عليّ نشر تطبيقي لتعمل واجهة API؟

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

هل يستطيع موقع ويب استدعاء واجهة API الخاصة بي من المتصفح؟

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

فقدت مفتاح API. هل يمكنني رؤيته مجددًا؟

لا، يُعرض المفتاح مرة واحدة فقط. أنشئ مفتاحًا جديدًا، وانقل الخدمة إليه، ثم انقر على إبطال بجانب المفتاح القديم.

لماذا لا أستطيع نشر نقطة نهاية؟

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

هل يمكنني تلقي webhooks عندما تتغير البيانات؟

ليس من الإدارة ← APIs، فهي تجيب عن الطلبات فقط. اطلب من MonstarX إضافة webhook إلى تطبيقك، مثل «عندما يُوضع طلب، أرسله بطلب POST إلى هذا العنوان».

صفحات ذات صلة

لوحة إدارة تطبيقكحيث توجد APIs مع جداولك ومستخدميك ونشاطك.

قاعدة بيانات تطبيقكالجداول التي تقرؤها نقاط النهاية وتكتب فيها.

الأسرار ومفاتيح APIالمفاتيح التي يستخدمها تطبيقك لخدمات أخرى.

استخدم MonstarX من وكيل البرمجة الخاص بكتحكّم في MonstarX نفسه من Claude Code وCursor وغيرها.