نظرة عامة على واجهة REST

تُقدَّم واجهة REST الخاصة بنظام Profound CMS بواسطة خدمة Rust translation_manager. وهي توفر نقاط نهاية للقراءة والتدفق بدون واجهة (headless) يستخدمها المُرسِم، بالإضافة إلى نقاط نهاية للكتابة للمحتوى، والترجمة، واستيراد CSV.

تستخدم جميع الأمثلة {CMS_API_URL} كعنوان أساسي (Base URL) لمضيف واجهة برمجة تطبيقات نظام إدارة المحتوى لديك (على سبيل المثال https://cms.dev.tryprofound.com). لا يوجد بادئة مسار عامة — تُركَّب المسارات عند الجذر، مثل {CMS_API_URL}/routes.

المصادقة

تستخدم الواجهة نظامي مصادقة منفصلين اعتمادًا على نقطة النهاية.

مفتاح واجهة برمجة التطبيقات (قراءات headless + إدراج/تحديث المتغير)

أرسل المفتاح في ترويسة x-api-key أو كمعامل استعلام api_key:

curl '{CMS_API_URL}/dataset/post?websiteId=<uuid>' \
  -H 'x-api-key: <your-api-key>'

يتم التحقق من المفاتيح مقارنةً بـ WorkOS وتُخزَّن مؤقتًا في الذاكرة لفترة وجيزة. بالنسبة لنقاط نهاية القراءة، لا يُطلَب مفتاح واجهة برمجة التطبيقات إلا عندما يضبط الخادم القيمة require_schema_api_key = true؛ وإلا فإن القراءات المجهولة مسموح بها. ويستلزم إدراج/تحديث المتغير (PATCH /dataset/{schema_name}) دائمًا وجود مفتاح صالح يحمل صلاحية content_write.

يستخدم مصادقة مفتاح واجهة برمجة التطبيقات: /routes, /route, /blocks*, /components*, /dataset/*, /schemas/*, /content-changes.

رمز JWT بصيغة Bearer (WorkOS)

تتطلب نقاط النهاية الإدارية رمز JWT لمستخدم WorkOS:

curl '{CMS_API_URL}/usage?orgId=<uuid>' \
  -H 'Authorization: Bearer <workos-jwt>'

يستخدم مصادقة Bearer: /translation, /translations, /usage, /csv.

تحديد موقع الويب (المستأجر)

تُحدِّد نقاط نهاية مفتاح واجهة برمجة التطبيقات موقع الويب المستهدف بهذا الترتيب:

1. معامل الاستعلام ?websiteId=<uuid>
2. ترويسة Host، وتُطابَق مع نطاق موقع ويب مُهيأ
3. المعامل الاحتياطي CMS_WEBSITE_ID (مستأجر واحد / تطوير محلي)

إذا لم يُحل أيٌّ منها إلى UUID صالح، تُرجِع نقطة النهاية الحالة 400.

نموذج الأخطاء

فحص الحالة

GET {CMS_API_URL}/health يُرجِع { "status": "ok" } ولا يحتاج إلى مصادقة — استخدمه لاختبارات الحيوية.