انتقل إلى المحتوى

مرجع الـ API — نظرة عامة

ما هو

سطح الـ HTTP API في ManpowerIQ، منظَّم حسب القدرة. هذه الصفحات مولَّدة من مواصفة OpenAPI الحيّة (/swagger/v1/swagger.json — 157 مسارًا، 215 عملية عبر 53 مجموعة وحدات تحكم) ومُعلَّمة بالأشياء التي لا تستطيع المواصفة حملها: التقييد حسب الدور (من مصفوفة RBAC)، والسبب، والمزالق، ونتائج الـ F. وهي لا تعيد إنتاج مخطط الطلب/الاستجابة الكامل لكل نقطة نهاية — فواجهة Swagger UI الحيّة على /swagger هي مصدر السجل لذلك؛ وكل صفحة تربط إليها.

أعراف مشتركة عبر كل نقطة نهاية

المصادقة. كل نقطة نهاية تتطلب Bearer JWT (عام security: [{ Bearer: [] }]) باستثناء مجموعة صغيرة من تلك الموسومة بـ [AllowAnonymous]: نقاط نهاية تسجيل الدخول وتشخيصات للتطوير فقط. الرمز هو رمز وصول مدته 8 ساعات (بدون تجديد) — انظر المصادقة وRBAC. التفويض لكل نقطة نهاية هو سياسة صلاحية (مثل [Authorize("employee.view")])؛ والرمز المطلوب مُدرَج في كل صفحة مجموعة ويُحلّ عبر مصفوفة RBAC.

الأخطاء — RFC 7807 ProblemDetails. تُرجع الإخفاقات جسم ProblemDetails:

Status Meaning
400 فشل التحقق (FluentValidation → ToValidationProblem)
401 لا رمز / رمز منتهٍ
403 مُصادَق عليه لكن تنقصه الصلاحية المطلوبة
404 غير موجود (أو نقطة نهاية للتطوير فقط جرى الوصول إليها خارج Development)
409 تعارض في المجال — يحمل extensions.code مُهيكلًا، مثل GRADE_PROTECTED / GRADE_REFERENCED (انظر عُرف الاستثناءات)

اللغة المحلية. مرّر Accept-Language: en أو ar (أو معامل الاستعلام locale حيث وُجد) لتعريب الرسائل؛ البيانات ثنائية اللغة تحمل Name_1_English / Name_2_Arabic — انظر التدويل.

ترقيم الصفحات لكل نقطة نهاية، لا عام. بعض نقاط نهاية القوائم تقبل Page/PageSize (أو take)؛ وكثير منها يُرجع مجموعة النتائج الكاملة. لا يوجد غلاف ترقيم صفحات عام — راجع Swagger لكل نقطة نهاية.

التسمية. المسارات بنمط kebab/أحرف صغيرة؛ وأسطح الـ admin-CRUD تعيش تحت /api/admin/* (انظر نمط التعايش).

المجموعات

النظام — المصادقة الشاملة، والهوية، والمنصة، وتشخيصات للتطوير فقط:

Admin — بيانات مرجعية وتهيئة CRUD:

التشغيلي — سير العمل اليومي:

الحالة الصادقة (محمولة إلى المرجع)

  • مجموعات الـ *Diagnostics الست هي للتطوير فقط ([AllowAnonymous]، مقيَّدة إلى IsDevelopment())؛ وثلاث منها تحمل TODO بـ "إزالة أو تقييد قبل الإنتاج". ليست تكاملات.
  • الموظفون والمهارات عبر الاستيراد فقط — لا توجد نقاط نهاية إنشاء/تحرير (Employees هي GET فقط)؛ يدخل الأشخاص عبر استيراد Excel.
  • LookupsController هو للقراءة فقط (كلها GET).
  • DemandPlanStatus.Locked قيمة تعداد معرَّفة لكن لا يمكن الوصول إليها (F1)؛ ونقطة Approved في الجدول المنشور ميتة (يذهب النشر مباشرة إلى Published).

ذات صلة