ملف OpenAPI لواجهة مُجيب البرمجية
ملف OpenAPI لواجهة مُجيب البرمجية يصف الطلبات الخمسة، وكل معامل فيها، وكل حقل في ردودها مع نوعه وهل يمكن أن يكون null، وكل خطأ، بصيغة OpenAPI 3.1. حمّله من openapi.json واستورده في الأداة التي تستخدمها.
ما الذي يصفه ملف OpenAPI؟
رابط القسم «ما الذي يصفه ملف OpenAPI؟»يصف الملف الواجهة كاملة كما تعمل اليوم:
- الخادم:
https://api.mujib.ai، والمسارات تبدأ بـ/api/v1. - المصادقة: طريقتان، الترويسة
Authorization: Bearer mjb_live_…أو الترويسةX-Api-Key. - الطلبات الخمسة بمعرّفاتها في الملف (
operationId):
operationId | الطلب | المرجع |
|---|---|---|
getMe | GET /api/v1/me | اختبار المفتاح |
listContacts | GET /api/v1/contacts | قائمة العملاء |
getContact | GET /api/v1/contacts/{id} | عميل واحد |
listBookings | GET /api/v1/bookings | قائمة الحجوزات |
getBooking | GET /api/v1/bookings/{id} | حجز واحد |
- المعاملات: كل معامل بنوعه وحدوده وقيمته الافتراضية، مثل
limitوcursorوsinceوfromوtoوstatus. - الردود: كل حقل بنوعه، والحقول التي قد تأتي
null، والقيم الممكنة لـstatusوstageوsource، مع أمثلة ببيانات مختلَقة. - الأخطاء: شكل الخطأ الموحّد
{ "error": { "code", "message" } }والردود 400 و401 و403 و404 و429 و500. - الترويسات:
X-RateLimit-LimitوX-RateLimit-RemainingوX-RateLimit-ResetوRetry-AfterوCache-Control.
كيف أستخدم الملف؟
رابط القسم «كيف أستخدم الملف؟»استورده في أداتك أو ولّد منه كودًا، فلا تكتب وصف الواجهة بيدك.
- حمّل openapi.json.
- استورده في أداة اختبار الطلبات التي تستخدمها، فتظهر لك الطلبات الخمسة جاهزة.
- ضع مفتاحك في إعدادات المصادقة في الأداة، بطريقة
Bearer، لا في الرابط. - أرسل
getMeأولًا لتتأكد أن المفتاح يعمل.
ويمكنك أيضًا:
- توليد عميل بلغتك: أي مولّد يقرأ OpenAPI
3.1يكتب لك الدوال والأنواع من الملف. - التحقق من الردود في اختباراتك: المخطّطات (schemas) في الملف تمنع الحقول غير الموثّقة، فتعرف إذا وصلك ما لم تتوقعه.
ما الإصدار الذي يصفه الملف؟
رابط القسم «ما الإصدار الذي يصفه الملف؟»يصف الملف الإصدار الأول من الواجهة، الذي تبدأ مساراته بـ /api/v1. ويحمل الحقل info.version تاريخ آخر تغيير بصيغة ISO، وهو التاريخ نفسه في سجل تغييرات API، فإذا تغيّر التاريخ فراجع السجل لتعرف ما الجديد.
ما الذي لا يصفه الملف؟
رابط القسم «ما الذي لا يصفه الملف؟»يصف الملف الطلبات التي ترسلها أنت إلى الواجهة فقط.
- أحداث Webhooks التي يرسلها مُجيب إلى رابطك، وطريقة التحقق من توقيعها، لها صفحاتها.
- خادم MCP الذي يربط ChatGPT وClaude بحسابك له صفحته.
- صفحات لوحة التحكم وطلباتها الداخلية ليست جزءًا من الواجهة العامة، فلا تبنِ عليها.
الأسئلة الشائعة
هل الملف مكتوب بيد أم مولَّد؟
مكتوب بيد ليطابق الواجهة كما تعمل، وكل حقل فيه منقول من الكود الذي يبني الردود.
هل يصف الملف Webhooks أيضًا؟
لا. يصف الطلبات التي ترسلها أنت إلى الواجهة. أحداث Webhooks وتوقيعها في صفحاتها.
كيف أعرف أن الملف تغيّر؟
يحمل الحقل info.version تاريخ آخر تغيير، وهو التاريخ نفسه في سجل تغييرات الواجهة.
مُجيب منتج شركة المجيب الذكي لتكنولوجيا المعلومات (ذات مسؤولية محدودة)، عمّان، الأردن. رقم التسجيل82888.