ابنِ على واجهات AHS المتاحة اليوم
استخدم عقد REST المنفّذ وWidget الويب المقيّد بأمان. يوضّح هذا التوثيق ما هو متاح الآن وما يزال مخططًا له.
بداية سريعة
تحقق من API المحلي بطلب واحد
طلب فحص النظام العام هو أصغر طلب آمن للتأكد من جاهزية البوابة المحلية واعتمادياتها المطلوبة.
- 1شغّل API المحلي واعتمادياته المطلوبة.
- 2أرسل الطلب من الطرفية.
- 3توقّع استجابة 200 داخل غلاف data القياسي.
curl --request GET \
+ --url http://localhost:8080/v1/system/ping \
+ --header 'Accept: application/json'حدود المصادقة
اختر بيانات الاعتماد حسب الـ endpoint
يصرّح كل إجراء في المرجع بمخطط الأمان الفعلي الخاص به. تبقى بيانات الاعتماد محصورة في غرض واحد ولا يجوز استبدال إحداها بالأخرى.
جلسة الإدارة
تستخدم لوحة التحكم ومسارات الإدارة cookie آمنة باسم ahs_session. وتتطلب طلبات المتصفح المغيّرة للحالة ترويسة X-CSRF-Token المقترنة بها. هذه المسارات ليست API بمفتاح خادم.
مفتاح Widget قابل للنشر
تقبل مسارات Widget ترويسة X-AHS-Publishable-Key من origin متصفح مسموح فقط. وتستخدم عمليات المحادثة أيضًا X-AHS-Conversation-Token قصير العمر. المفتاح القابل للنشر مقيّد وظاهر للمتصفح وليس سرًا إداريًا.
مفتاح API سري للخادم
تستدعي خوادم Backend الموثوقة POST /v1/answers عبر X-AHS-API-Key من دون Origin متصفح. يمكن تقييد المصدر بقائمة IP دقيقة واختيارية. لا تضع هذا السر في كود المتصفح أو الموبايل.
بيئتا Test وProduction
يبدأ كل مشروع ببيئتي Test وProduction معزولتين. تبقى المعرفة والإعدادات والمحادثات والمفاتيح القابلة للنشر ومفاتيح الخادم مرتبطة ببيئتها المحددة.
أخطاء متسقة
تستخدم أخطاء API غلاف ErrorEnvelope الموثق. عالج حالة HTTP ورمز الخطأ المستقر، واعرض الرسالة بأمان، واحتفظ بـ X-Request-ID عند الحاجة لتتبّع الطلب.
حدود طلبات حسب العملية
قد تعيد عمليات البحث والتوليد وWidget المحمية حالة 429. تختلف الحدود حسب العملية والنطاق، لذلك استخدم التراجع التدريجي بدل افتراض حصة عامة واحدة.
OpenAPI 3.1
مرجع تفاعلي للـ API المنفّذ
ابحث في المسارات وافحص المخططات ومتطلبات الأمان وانسخ أمثلة الطلبات أو نزّل ملف YAML الأساسي. تجربة أي طلب تظل بحاجة لبيانات الاعتماد المعلنة للعملية.