كيف تعمل واجهة API في Optifora
تصف هذه الصفحة شكل واجهة API: كيف تُثبَت الهوية، وكيف تتقدم الإصدارات، وما الحدود التي يبقى الطلب ضمنها، وكيف يبدو الخطأ، وكيف تُتبادل البيانات مع الخارج.
المنتج قيد التطوير وسطح واجهة API ما زال قيد الاستكمال. وسيُنشر مستند مرجعي لنقاط النهاية على حدة؛ أما هذه الصفحة فلا تحمل أي عنوان ولا أي نداء نموذجي، بل تشرح آلية العمل فقط.
التحقق من الهوية
كل طلب يعود إما إلى شخص وإما إلى تطبيق مسجَّل. والطلب الذي يصل إلى نقطة نهاية محمية دون هوية يعود بردٍّ يفيد بعدم التحقق من الهوية.
- رمز حامل (Bearer)ينتقل رمز الوصول في ترويسة التفويض الخاصة بالطلب. وهو موقَّع، ولا يحمل سوى هوية صاحب الطلب.
- عمر قصيرتنتهي صلاحية رمز الوصول بعد مدة تُقاس بالدقائق؛ وطول هذه المدة إعداد يُضبط عند النشر وقيمته الافتراضية ثلاثون دقيقة.
- التجديد والتدويرتُمدَّد الجلسة برمز تجديد، وكل تمديد يصدر زوجًا جديدًا من الرموز. وإذا قُدِّم رمز تجديد مستهلك مرة ثانية، أُلغيت جميع جلسات ذلك الشخص.
- الصلاحيات ليست مضمَّنة في الرمزالرمز يحمل الهوية فقط؛ أما ما يُسمح للشخص برؤيته فيُسأل عنه قاعدة البيانات مع كل طلب. لذلك تتوقف الصلاحية المسحوبة عن العمل قبل انتهاء صلاحية الرمز الذي بيد صاحبه.
- مفتاح جهة التكامليتصل التطبيق المسجَّل بمفتاحه الخاص. تُعرض القيمة الصريحة مرة واحدة فقط عند الإنشاء؛ أما المحفوظ فهو بصمتها المشفَّرة والبادئة غير السرية التي تتيح التعرف على المفتاح.
- المؤسسة هي من تمنح صلاحية الوصولمهما كان التطبيق واسع الانتشار، فإنه لا يرى صفًّا واحدًا من البيانات دون إذن مسجَّل من المؤسسة. والإذن مؤرَّخ ومحدَّد النطاق وقابل للإلغاء.
إدارة الإصدارات
- الإصدار يقع داخل المسارتُنشر نقاط النهاية خلف بادئة إصدار؛ والسطح الحالي هو الإصدار الأول.
- التغيير الكاسر يفتح مسارًا جديدًالا يُكسر عقد نقطة نهاية قائمة في مكانها. بل يُنشر التغيير غير المتوافق على مسار إصدار جديد بينما يستمر القديم في العمل.
- المستند يعلن إصداره بنفسهيحمل المرجع رقم الإصدار الذي وُلِّد منه؛ فالمستند نفسه يجيب عن سؤال أي إصدار تقرأ.
البيئات والحدود
يعلن المرجع بيئتين: بيئة الإنتاج وبيئة التطوير المحلي. ويُسلَّم العنوان الجذر إلى جهة التكامل مع مفتاحها؛ ولا يُنشر في هذه الصفحة.
- الحيوية والجاهزية تُقاسان على حدةنقطة نهاية واحدة تفيد بأن العملية تعمل؛ والثانية ترسل استعلامًا حقيقيًا إلى قاعدة البيانات وتؤكد إمكان الوصول إليها. والثانية وحدها هي التي تقرر ما إذا كان ينبغي توجيه حركة الطلبات.
- أصول المتصفح محصورة في قائمةلا تُقبل الطلبات العابرة للأصول إلا من أصول معلنة مسبقًا؛ وما دامت القائمة فارغة، يُرفض أي طلب متصفح عابر للأصول.
- حد حجم الجسملا يجوز أن يتجاوز جسم الطلب خمسة ميغابايت. أما المجموعات الكبيرة فتنتقل بوصفها مهمة نقل جماعي لها سجل حالة خاص بها، لا بوصفها طلبًا واحدًا.
- الأسرار لا تُكتب في السجللا يحتفظ سجل الخادم بأي ترويسة تفويض ولا ملف تعريف ارتباط ولا كلمة مرور ولا رقم هوية وطنية.
حد المعدل
يُحسب الحد لكل عنوان ولكل دقيقة. والقيمة الافتراضية 120 طلبًا في الدقيقة وتُضبط عند النشر. ويُبلَّغ عن الرصيد المتبقي في ترويسات كل رد.
| ترويسة الرد | دلالتها |
|---|---|
| x-ratelimit-limit | إجمالي المسموح به داخل النافذة الزمنية. |
| x-ratelimit-remaining | ما تبقى ضمن هذه النافذة الزمنية. |
| x-ratelimit-reset | الثواني المتبقية حتى تجديد الحصة. |
| retry-after | عدد الثواني قبل إعادة المحاولة. ولا يظهر إلا في الرد الذي رفض الطلب. |
بمجرد تجاوز الحد يُرفض الطلب ويذكر الرد مدة الانتظار بالثواني. وتُعاد المحاولة بعد انقضاء تلك المدة، لا على الفور.
صيغة الخطأ
يعود كل خطأ في الغلاف نفسه: حقل رمز مختصر تتفرع عليه الآلة، وحقل شرح يقرأه الإنسان.
- errorالرمز المختصر الذي يبني عليه العميل قراره.
- messageشرح ما حدث.
| الحالة | حقل الرمز | المعنى |
|---|---|---|
| 400 | Bad Request | الطلب لا يطابق المخطط. ويذكر الشرح اسم الحقل الناقص أو غير الصالح. |
| 401 | unauthenticated | لا توجد هوية صالحة: لم يُرسَل رمز، أو انتهت صلاحيته، أو لم يجتَز التحقق. |
| 404 | Not Found | لا وجود لنقطة النهاية هذه، أو لا وجود لهذا السجل. |
| 429 | Too Many Requests | تم تجاوز حد المعدل؛ ويذكر الرد مدة الانتظار اللازمة. |
| 5xx | internal_error | عطل غير متوقع. لا تُسلَّم تفاصيله إلى العميل، بل تُكتب في سجل الخادم. |
تقسيم الصفحات
نقاط النهاية التي تعيد قوائم تأخذ المعاملين نفسيهما وتعيد العدادات نفسها، فلا يُعاد كتابة عميل التصفح لكل نقطة نهاية.
- limitعدد السجلات التي ينبغي أن تحملها الصفحة الواحدة. الحد الأدنى واحد والحد الأقصى مئتان؛ وخمسون عند عدم التحديد.
- offsetعدد السجلات التي تُتخطى. ويبدأ من الصفر.
- totalعدد السجلات المطابقة للمرشحات إجمالًا.
- countعدد السجلات التي يحملها هذا الرد فعليًا.
يعيد الرد أيضًا قيمتي الحد والإزاحة اللتين استخدمهما؛ فيقرأ العميل موضعه من الجواب بدل أن يخمّنه.
تبادل البيانات وخطافات الويب
نمط التبادل إعداد لا منتج منفصل: فكل تطبيق مسجَّل يحمل في سجله النمط الذي يعمل به.
| النمط | المعنى |
|---|---|
| اتجاه واحد — صادر | ينشر Optifora البيانات؛ والطرف الآخر يقرؤها أو يشترك في الأحداث. |
| اتجاه واحد — وارد | يدفع الطرف الآخر البيانات؛ ويتحقق Optifora منها ثم يكتبها. |
| اتجاهان | يكتب الطرفان معًا؛ وقاعدة حل التعارض محددة سلفًا. |
| تصافح | كل عملية نقل تفتح جلسة: عرض، ثم تحقق، ثم موافقة، ثم نقل، ثم إيصال. ويبقى الإيصال لدى الطرفين. |
- الأحداث تُدفع إلى الخارجيرسل خطاف الويب الحدث إلى عنوان الاستدعاء الراجع الذي أعلنه التطبيق المسجَّل. والحدث الذي يتعذر تسليمه يبقى في الطابور وتُعاد محاولته؛ ولا يُسقَط بصمت أبدًا.
- الطلب نفسه لا يكتب مرتينيحمل طلب الكتابة مفتاح عدم التكرار. والطلب الثاني الحامل للمفتاح نفسه لا ينشئ سجلًا ثانيًا.
- كل نداء يُقاسمَن نادى، ومتى، وبأي نطاق، وبأي نتيجة — كل ذلك مسجَّل. والسجل نفسه يجيب عن تتبع الأعطال وعن سؤال مَن سحب هذه البيانات.
- تطبيقاتنا تدخل من الباب نفسهلا وجود لمسار ثانٍ ذي امتيازات. فتكاملنا الخاص دليل على السطح نفسه الذي يلقاه المطور الخارجي.
نموذج البيانات الخاص بطبقة التبادل جاهز؛ أما نقاط نهايتها فلم تُنشر بعد. وحين تُنشر، سيربط هذا القسم بمدخلاتها في المرجع.
المستندات المرجعية
لا يُكتب المرجع يدويًا؛ بل يُولَّد من مخططات نقاط النهاية. وكلما سلَّمت نقطة نهاية مخططها امتلأ المستند من تلقاء نفسه، فلا يمكن أن يفترق المستند عن السلوك الفعلي.
- اليوم: قيد الإعدادتتقدم المخططات وحدةً وحدة. وقبل نشر المستند، سيكون طلب كل نقطة نهاية وردها ظاهرين فيه.
- ستُنشر صيغتانمستند OpenAPI قابل للقراءة آليًا، وصفحة مرجعية مستخرجة من المستند نفسه ويمكن تصفحها في المتصفح.
- الوصول متدرجالنظرة العامة مفتوحة للجميع. أما المرجع الكامل فقد يقع خلف رمز توثيق يُمنح لجهة تكامل مسجَّلة؛ ومفاتيح الإنتاج وعناوين الاستدعاء الراجع ليست شأنًا توثيقيًا أصلًا — فهي تخص سجل التطبيق نفسه.
- معيار العناوينيُنشر مرجعان وعنواناهما ثابتان: العنوان client-api.optifora.com/docs مفتوح، والعنوان admin-api.optifora.com/docs يتطلب تفويضًا ومغلق أمام الخارج. وليس أي منهما قيد التشغيل اليوم؛ وستُضاف الروابط إلى هذا القسم حين يعملان.
إن كانت خطة التكامل لديك واضحة بالفعل، فاكتب إلينا من صفحة التواصل: ستكون بين أوائل من يُبلَّغون عند فتح السطح.
هل لديك طلب محدد؟
تشرح هذه الصفحات كيف تسير عملية الدعم. وإن كان لديك طلب أو سؤال فاكتب إلينا من صفحة التواصل.
انتقل إلى صفحة التواصل