تخطَّ إلى المحتوى
CHAMPREPCHAMPREPCHAMPREP Docs

API Gateway نظرة عامة

يُعدCHAMPREPAPI Gateway نقطة الدخول العامة لتكاملات المنصات المدعومة . فهو يتحقق من صحة بيانات الاعتماد، ويفحص النطاقات والوصول إلى الخدمة، ويفرض ضوابط الاستخدام الحالية، ويوجه الطلبات المقبولة إلى الخدمة CHAMPREPذات الصلة.

عنوان URL الأساسي

Section titled “عنوان URL الأساسي”
https://api.champrep.com/v1

يتم إصدار إصدارات المسارات العامة المنسقة تحت /v1. استخدم عنوان URL الكامل عبر بروتوكول HTTPS في تطبيقات الخادم واستخدم تكوين البيئة بدلاً من توزيع عنوان URL الأساسي في جميع أنحاء الكود الخاص بك.

أول طلب مصادق عليه

Section titled “أول طلب مصادق عليه”

قم بإنشاء مفتاح محدد النطاق في API المفاتيح، ثم قم بتمريره كـ بيانات اعتماد حامل:

Terminal window
curl --fail-with-body \
  --header "Authorization: Bearer $CHAMPREP_TOKEN" \
  --header "Accept: application/json" \
  https://api.champrep.com/v1/auth/whoami

لا تضع أبدًا مفتاحًا حقيقيًّا في نظام التحكم في المصادر، أو حزمة المتصفح، أو ملف ثنائي للجوال، أو رسالة دعم، أو الوثائق. استخدم مدير الأسرار من جانب الخادم لـ عمليات التكامل التي تم نشرها.

قواعد الطلبات

Section titled “قواعد الطلبات”
  • أرسل واستقبل JSON ما لم تصف نقطة النهاية صراحةً نوع وسائط آخر .
  • استخدم الطوابع الزمنية ISO 8601 مع منطقة زمنية صريحة لقيم التاريخ والوقت.
  • قم بترميز المسار وقيم الاستعلام باستخدام ترميز URL.
  • احتفظ ببيانات اعتماد الحامل في Authorization الرأس.
  • تعامل مع المعرفات على أنها سلاسل غير شفافة؛ لا تستنتج تنسيقها ولا تقم بتكوينها محليًّا.
  • استخدم المسارات المُنتقاة /v1 المسارات في مرجع نقاط نهاية الخدمة.

SDKsقد تستخدم الخدمة الرسمية مسارات توافق البوابة أثناء ترحيل الخدمة إلى خدمة مُنتقاة /v1 . طبقة التوافق هذه مخصصة لـ SDK؛ يجب ألا تنسخ عمليات التكامل المباشرة الجديدة المسارات الخاصة بالخلفية من حركة مرور المتصفح أو SDKالعمليات الداخلية.

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

Section titled “مغلفات الاستجابة”

تتخذ الاستجابات التي تم تكوينها بنجاح عبر البوابة الشكل التالي:

{
  "success": true,
  "data": {}
}

تتخذ أخطاء البوابة الشكل التالي:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "A safe explanation of the error.",
    "status": 400
  }
}

تحتفظ بعض استجابات الخدمات التي يتم توجيهها عبر الوكيل بمغلف البيانات الخاص بالخدمة. تحقق دائمًا من حالة HTTP أولاً، ثم اقرأ success, data، أو error عند وجودها. انظر الأخطاء والحدود والمحاولات المتكررة من أجل معالجة الأخطاء القابلة للنقل.

تدفق المصادقة والتفويض

Section titled “تدفق المصادقة والتفويض”

يتم تقييم كل طلب خدمة بالترتيب التالي:

  1. تقوم البوابة بالتحقق من صحة المفتاحAPI وأي قيود IP تم تكوينها.
  2. تم تحديد نافذة استخدام البوابة الحالية.
  3. API Gateway يتم التحقق من الوصول إلى خريطة الخدمة وفقًا للخطة والملف الشخصي النشطين.
  4. تم التحقق من الوصول إلى الخدمة الوجهة.
  5. يتم مقارنة نطاق المفتاح بالمسار وطريقة HTTP.
  6. تطبق الخدمة الوجهة فحوصاتها الخاصة المتعلقة بالأدوار والمؤسسة والموارد و الحصص.

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

إصدارات

Section titled “إصدارات”

جزء عنوان URL الأول هو APIالإصدار الرئيسي. قد تظهر حقول استجابة إضافية و نقاط نهاية جديدة ضمن الإصدار الرئيسي. يجب أن تتجاهل عمليات التكامل الحقول غير المعروفة وألا تعتمد على الحقول غير الموثقة أو ترتيبها.

استخدام GET /v1/version للحصول على معلومات إصدار البوابة العامة. خطط لعمليات الترحيل إلى إصدار رئيسي مستقبلي بشكل صريح بدلاً من إعادة الكتابة /v1 المسارات في وقت التشغيل.

الخطوات التالية

Section titled “الخطوات التالية”