REST API

أين في البوابة: مرجع API في https://<your-domain>/apidoc (عام) ومفاتيح API في /api-keys. أين في لوحة المشرف: Customers › API keys (/customers/apikeys) يعرض المفاتيح التي أنشأها العملاء.

الوظيفة

كل إجراء يمكن للعميل القيام به في البوابة — سرد الأجهزة الظртуаية والتحكم بها، قراءة الفواتير، إدارة SSH Keys، Kubernetes، التخزين، تذاكر الدعم — متاح عبر REST API مُوَصَّل بالإصدارات تحت https://<your-domain>/v1/. يستدعي العملاء ذلك من النصوص البرمجية وCI باستخدام API key بنطاق محدد. نفس الـ API يغذي cmp command-line tool وMCP server، ويتم إنشاء المرجع من التثبيت قيد التشغيل، لذا فهو يعرض دائماً بدقة الميزات التي قمت بتفعيلها.

المتطلبات

العنصر	المتطلب
عنوان HTTPS العام	يتم تقديم API على نطاقك الرئيسي (وعلى نطاق كل موزع خاص به).
An API key	تم إنشاؤها بواسطة العميل في البوابة؛ راجع API keys.
الاعتمادات	لا شيء. نقاط النهاية لوحدة لم تقم بتفعيلها (مثل Kubernetes أو Object Storage) مخفية من المرجع ومرفوضة.

تجهيز البنية التحتية

لا شيء لتثبيته. إذا كان هناك خادم وكيل عكسي (reverse proxy) أمام NexCMP، فقم بتوجيه /v1/ و/mcp و/cli/ و/apidoc إلى لوحة التحكم (تكوين nginx الخاص بالمثبت يقوم بذلك بالفعل).

الربط في NexCMP

The interactive reference

افتح https://cloud.example.com/apidoc (استبدل المضيف بنطاقك؛ ويرى عملاء الموزع المرجع على نطاق الموزع، مع اسم الموزع). يحتوي على توثيق لنقاط النهاية مع أمثلة للطلب والاستجابة بلغة curl، وcmp CLI، وJavaScript، وPython، وGo، ومربع بحث (Ctrl أو Cmd + K)، ولوحة Try it. ترسل ميزة Try it الطلبات إلى نفس الموقع فقط، باستخدام مفتاح يلسقه الزيارة (يُحفظ في جلسة المتجر)؛ وهي للقراءة فقط افتراضياً، وتتطلب استدعاءات الكتابة أو المدفوعة مفتاح تبديل إضافياً وتأكيداً.

التنزيلات والمستندات القابلة للقراءة آلياً

جميعها عامة ولا تحتاج إلى مفتاح ويتم إنشاؤها لكل موقع:

URL	المحتوى
`/apidoc`	المرجع التفاعلي.
`/v1/public/openapi.json`	مستند OpenAPI 3.1.
`/v1/public/openapi.yaml`	نفسه، بصيغة YAML.
`/v1/public/postman.json`	مجموعة Postman.
`/v1/public/insomnia.json`	تصدير Insomnia.
`/v1/public/api.md`	المرجع في ملف Markdown واحد.
`/v1/public/api-catalog`	JSON خفيف: العلامة التجارية، عنوان URL الأساسي، بادئة المفتاح، كل نطاق (scope) وكل نقطة نهاية مع طريقة الاتصال، والمسار، والنطاق، وما إذا كانت تتطلب `Idempotency-Key`.

bash

curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40
curl -sO https://cloud.example.com/v1/public/openapi.yaml

في Postman، اختر Import › Link والصق https://cloud.example.com/v1/public/postman.json. توفر صفحة المرجع أيضاً عملاء API بملف واحد לـ JavaScript وPython.

المصادقة

أرسل المفتاح في ترويسة Authorization:

bash

curl -s https://cloud.example.com/v1/billing/wallet \
  -H "Authorization: Bearer vk_XXXX"

تبدأ مفاتيح العملاء بـ vk_. المفاتيح مرتبطة بالموقع: المفتاح الذي يتم إنشاؤه على cloud.example.com لا يعمل على نطاق الموزع.
رموز جلسات المتصفح (pt_...) مخصصة للوحة التحكم فقط؛ استخدم مفتاحاً للأتمتة.
تحدد نطاقات (scopes) المفتاح ما يُسمح له باستدعائه؛ ويُرجع النطاق المفقود خطأ HTTP 403 scope_required. راجع API keys.
تحقق من المفتاح باستخدام GET /v1/apikeys/self: فهو يُرجع اسم المفتاح المستدعي ونطاقاته وتاريخ انتهاء صلاحيته ومعدل الطلبات المتبقي المسموح به (يمكن لكل مفتاح استدعاؤه).

الأمثلة

bash

# List virtual machines
curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX"

# Start one (needs vm:write)
curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \
  -H "Authorization: Bearer vk_XXXX"

# Create a VM (paid: needs vm:create and an Idempotency-Key)
curl -s -X POST https://cloud.example.com/v1/vm \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @vm.json

خذ حقول الطلب الدقيقة لكل عملية من /apidoc.

الأخطاء

كل خطأ هو بتنسيق JSON مع قيمة code ثابتة وmessage مقروءة بشرياً:

json

{"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}}

HTTP	الرمز النموذجي `code`	المعنى
401	`unauthenticated`, `key_invalid`, `key_revoked`, `key_expired`, `key_ip_denied`, `site_mismatch`, `api_keys_disabled`	مفتاح مفقود أو غير معروف، مُلغى، منتهي الصلاحية، عنوان IP للمستدعي خارج قائمة السماح الخاصة بالمفتاح، مفتاح من موقع آخر، أو مفاتيح API معطلة.
403	`scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden`	المفتاح يفتقر إلى النطاق؛ نقطة النهاية غير متوفرة للمفاتيح؛ الحساب مقفل؛ تم بلوغ quota؛ إجراء غير مسموح به في جلسة منتحلة.
404	`not_found`	غير موجود — يُعاد أيضاً للموارد التي تملكها جهة أخرى.
422	`invalid_argument`	خطأ تحقق (الحقل المُسمَّى في الاستجابة).
429	`rate_limited`	طلبات كثيرة جداً؛ انتظر حتى `Retry-After`.
503	`maintenance`	وضع الصيانة مفعل: عمليات القراءة تعمل، وعمليات الكتابة مرفوضة.

حدود المعدل

الحد	القيمة الافتراضية
لكل مفتاح	120 طلباً في الدقيقة
لكل حساب (جميع المفاتيح معاً)	300 طلب في الدقيقة

تحمل كل استجابة X-RateLimit-Limit، وX-RateLimit-Remaining، وX-RateLimit-Reset؛ وتضيف استجابة 429 الحقل Retry-After.

منع التكرار

الأوامر التي تكلف مالاً أو لا يمكن تكرارها (إنشاء، تغيير الخطة، شراء، حذف ...) تتطلب ترويسة Idempotency-Key (أي سلسلة نصية تصل إلى 200 حرف؛ يعد معرف UUID خياراً جيداً). أرسل نفس المفتاح مرة أخرى بعد انتهاء المهلة وسيعيد الخادم النتيجة الأصلية (مع Idempotency-Replayed: 1) بدلاً من تكرار العملية. إعادة استخدام المفتاح لأمر مختلف يُرجع 422؛ والطلب الذي لا يزال قيد التنفيذ يُرجع 409/Retry-After. بدون هذه الترويسة، يتم رفض الطلب المدفوع.

التحقق

أنشئ مفتاحاً بنطاق vm:read في لوحة التحكم (API keys › Create key).
تنفيذ:
bash
```
curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX"
```
ستحصل على HTTP 200 وترويسات الحد الأقصى للمعدل.
curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" يعرض الأجهزة الوهمية للحساب. في البوابة، يظهر عمود Last used للمفتاح وKey usage log الاستدعاءات.

الحدود والملاحظات

غير متاح للمفتاح أبداً: تعبئة الرصيد، السحب، تغيير البطاقات أو التعبئة التلقائية، تغيير كلمة المرور، البريد الإلكتروني أو المصادقة الثنائية (2FA)، حذف الحساب، أو إنشاء أو تعديل أو إلغاء مفاتيح أخرى. تتطلب هذه الإجراءات جلسة متصفح مسجلة الدخول.
الوحدات المخفية: يعرض المرجع ومستند OpenAPI فقط الميزات المُفعّلة على ذلك الموقع.
حجم الاستجابة والتقسيم إلى صفحات: نقاط نهاية القوائم مُقسمة إلى صفحات (page، per_page)؛ اقرأ مستند OpenAPI لكل نقطة نهاية.
الوقت والمال: المبالغ المالية تكون بسنتات USD ما لم يُذكر اسم الحقل بخلاف ذلك.
واجهة برمجة تطبيقات المشرف: وحدة تحكم المشرف لها صفحة System › Admin › API الخاصة بها ومفاتيح المشرف (ofw_...) للإدارة؛ وهي منفصلة عن واجهة برمجة تطبيقات العملاء الموضحة هنا.
إصدار النسخ: بادئة المسار /v1 ثابتة؛ وقد تُضاف حقول جديدة إلى الاستجابات.

استكشاف الأخطاء وإصلاحها

العَرَض	السبب	الحل
401 على مفتاح جديد	المفتاح من نطاق آخر، أو منتهي الصلاحية، أو مُدخَل بمسافات	أنشئ المفتاح على النطاق الذي تستدعيه؛ وتحقق من رأس `Authorization: Bearer vk_...`.
403 `scope_required`	نطاق مفقود	عدّل المفتاح في البوابة وأضف النطاق.
401 `key_ip_denied` أو `site_mismatch`	المفتاح مقصور على عناوين IP أخرى ("allowed IPs") أو مُنشأ على نطاق آخر	أضف عنوان IP الخاص بخادمك إلى عناوين IP المسموح بها للمفتاح، أو استدعِ النطاق الذي أُنشئ فيه المفتاح.
404 على جهاز وهمي موجود	الجهاز الوهمي ينتمي إلى حساب آخر	استخدم مفتاح المالك.
400/422 تطلب `Idempotency-Key`	عملية مدفوعة بدون الرأس المطلوب	أضف `Idempotency-Key: <uuid>`.
429	تجاوز الحد المسموح به	تراجع؛ واستخدم `Retry-After`.
`/apidoc` يعرض أقل من المتوقع	الوحدة مُعطّلة	فَعِّل الوحدة في License & updates.

REST API ​

الوظيفة ​

المتطلبات ​

تجهيز البنية التحتية ​

الربط في NexCMP ​

The interactive reference ​

التنزيلات والمستندات القابلة للقراءة آلياً ​

المصادقة ​

الأمثلة ​

الأخطاء ​

حدود المعدل ​

منع التكرار ​

التحقق ​

الحدود والملاحظات ​

استكشاف الأخطاء وإصلاحها ​

REST API

الوظيفة

المتطلبات

تجهيز البنية التحتية

الربط في NexCMP

The interactive reference

التنزيلات والمستندات القابلة للقراءة آلياً

المصادقة

الأمثلة

الأخطاء

حدود المعدل

منع التكرار

التحقق

الحدود والملاحظات

استكشاف الأخطاء وإصلاحها