لوحة تحكم أهدى.

نموذج موارد واضح

ينبغي أن يعمل التكامل بمعرّفات خوادم ومناطق وصور وخطط وعمليات صريحة. ينبغي أن تُرجع طلبات الإنشاء وإعادة التثبيت عملية يمكن التحقق منها حتى الاكتمال. طلب HTTP الناجح ليس الشيء نفسه كأن تكون الآلة جاهزة.

بيانات اعتماد بمهمة محدودة

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

إعادة المحاولة لازم تكون آمنة

ممكن يحصل انتهاء مهلة الشبكة بعد ما العملية تتقبل. استخدم مفتاح تكرار للإنشاء والطلبات الحساسة للدفع، وافحص حالة العملية واحترم حدود المعدل. إعادة المحاولة المفروض تحل الغموض، مش تنشئ سيرفر إضافي بيتحاسب عليه.

اتأكد من التوافق قبل الدمج

تحقق من إصدار API الصادر، ونموذج المصادقة، وصيغ الأخطاء، وتقسيم الصفحات، وحدود المعدل، ونطاقات الرموز قبل بناء التكامل. استخدم فقط حزم KoalaVPS SDK المنشورة من روابط إصدار موثّقة.

خارطة طريق API

خريطة طريق API بتغطي اكتشاف الكتالوج، والمصادقة، وحالة الحساب، والفوترة بالعملات الرقمية، ودورة حياة السيرفر، ومفاتيح SSH العامة، والويب هوكس. المسارات اللي تحت بتوصف عقد الواجهة؛ الوصول للإنتاج لسه مش متاح.

مسارات المصادقة وإدارة الحساب

يفصل عقد API بين جلسات تسجيل الدخول ومفاتيح API. تحقق من مخططات الاستجابة والأخطاء وأعمار الرموز وإجراءات الاسترداد المدعومة مقابل الإصدار الصادر لتكاملاتك.

• POST /v1/auth/register
• POST /v1/auth/login
• POST /v1/auth/login/totp
• POST /v1/auth/token/refresh
• POST /v1/auth/recover
• GET /v1/auth/sessions
• DELETE /v1/auth/sessions/{token_id}
• POST /v1/auth/totp/setup
• POST /v1/auth/totp/enable
• POST /v1/auth/totp/disable
• POST /v1/auth/password
• POST /v1/auth/api-keys
• GET /v1/auth/api-keys
• DELETE /v1/auth/api-keys/{key_id}
• GET /v1/account
• PATCH /v1/account
• GET /v1/account/usage
• GET /v1/account/audit-log

مسارات الكتالوج والفوترة

قراءة الكتالوج ماينفعش تتطلب دفع. إنشاء الدفع محتاج نطاق فواتير مقيّد، وحالة فاتورة واضحة، ومعالجة آمنة من التكرار. التأكيد لازم يكتمل قبل تفعيل الخدمة.

• GET /v1/catalog
• GET /v1/catalog/vps
• GET /v1/catalog/dedicated
• GET /v1/catalog/regions
• GET /v1/catalog/images
• GET /v1/catalog/{code}
• GET /v1/billing/coins

السيرفر ومسارات الوصول

تتطلب دورة الحياة تأكيدًا صريحًا لعمليات الإلغاء وإعادة التثبيت. مفاتيح SSH الخاصة تنتمي إلى العميل؛ تحتاج الخدمة فقط إلى نظيراتها العامة.

• POST /v1/servers
• GET /v1/servers
• GET /v1/servers/{order_number}
• PATCH /v1/servers/{order_number}
• DELETE /v1/servers/{order_number}
• POST /v1/ssh-keys
• GET /v1/ssh-keys
• GET /v1/ssh-keys/{id}
• DELETE /v1/ssh-keys/{id}

الأحداث والمعلومات العامة

الـ webhooks محتاجة توقيعات قابلة للتحقق وإعادة محاولات محدودة وحماية من إعادة التشغيل. نقاط نهاية الثقة العامة المفروض ترجع أدلة حقيقية بتاريخ بدل تطمينات مصطنعة.

• POST /v1/webhooks
• GET /v1/webhooks
• DELETE /v1/webhooks/{id}
• POST /v1/webhooks/{id}/test
• GET /v1/transparency/canary
• GET /v1/transparency/peering
• GET /v1/transparency/status
• GET /v1/agents/directory
• POST /v1/agents/directory

التصريح وحدود حركة المرور

نموذج نطاق مرشح هو قراءة وخوادم وفوترة وكامل، بحد أقصى عشرة مفاتيح نشطة لكل حساب. يقترح عقد API ميزانيات طلبات قدرها 120 في الدقيقة و3,000 في الساعة لمفتاح API، و30 في الدقيقة لحركة المرور العامة. تحقق من HTTP 429 وRetry-After ونافذة التنفيذ في وثائق API الصادرة؛ ميزانيات خارطة الطريق هذه ليست التزامًا بسعة الإنتاج.

• POST /v1/oauth/register
• POST /v1/oauth/token
• POST /v1/oauth/revoke
• GET /v1/oauth/introspect

SDK وإصدارات البروتوكول

تشمل خارطة طريق التكامل REST ونقطة نهاية MCP مستضافة وحزمة stdio بإصدارات وSDKs وواجهة سطر أوامر. تحقق من توفر الإصدارات وبيئات التشغيل المدعومة والمجاميع الاختبارية وتوافق API قبل تثبيت عميل. التنزيلات الإنتاجية غير متاحة بعد.

موارد API، مجمعة حسب المسؤولية

يفصل API المقصود بين الوصول إلى الحساب وقراءة الكتالوج والفوترة ودورة حياة الخادم ومفاتيح SSH وعمليات الاستدعاء. لا ينبغي أن تنشئ الاستدعاءات للقراءة فقط طلبًا، ولا ينبغي أن يصرّح اعتماد الفوترة تلقائيًا بتغييرات أمان الحساب. هذا يصف عقد التكامل. نقطة نهاية تزويد الإنتاج وSDK الصادر غير متاحين عبر هذا الموقع.

• الحساب: الجلسات والاستخدام وأحداث تدقيق الأمان
• الكتالوج: الخطط والمناطق والصور المتاحة
• السيرفرات: الإنشاء والفحص والتعديل والإلغاء
• مفاتيح SSH: سجّل المواد العامة وأبطل المفاتيح القديمة
• Webhooks: سجّل وافحص واختبر وامسح الاستدعاءات الموقعة

يجب أن يبقى طلب الخادم صغيرًا

اختار معرّف خطة قياسي ومنطقة وصورة نظام تشغيل واسم مضيف. حد اسم المضيف المقصود هو 64 حرف. الخدمة الشغالة ممكن تولّد سر مسؤول بشكل خاص أو تقبل مفتاح عام SSH مسجّل. إضافات القرص وGPU وNIC وIP العشوائية مش ضمنية من طلب خطة قياسي. ارفض الحقول غير المدعومة بدل ما تحاسب بصمت على ترقية تخمينية.

{
  "plan": "KV-D3",
  "region": "hel",
  "image": "ubuntu-24",
  "hostname": "private-node-01"
}
// Example request schema; validate against a released API before integration.

النطاقات وحدود المفاتيح جزء من العقد

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

انشر حدود المعدل وسلوك إعادة المحاولة مع بعض

الحدود المقترحة هي 120 طلب في الدقيقة و3,000 في الساعة لمفتاح API، و30 طلب في الدقيقة لطلبات الكتالوج العام غير المصادق عليها. دي قيم سياسة مخططة، مش سعة API مقاسة. التنفيذ الفعلي محتاج استجابة 429 متسقة وإرشادات Retry-After وتراجع محدود من العميل. طلبات الإنشاء والدفع كمان محتاجة مفاتيح idempotency ثابتة.

الويب هوكس رسائل ممكن توصل أكتر من مرة

مستقبِل رد النداء لازم يتحقق من التوقيع على الجسم الأصلي، ويرفض الطوابع الزمنية خارج النافذة المسموحة، ويتذكر معرّفات الأحداث المعالجة. احفظ الحدث قبل الإقرار به، وبعدها طبّق التغيير بشكل idempotent. خلّي محاولات التسليم ومسار إعادة التشغيل اليدوي ظاهرين. رد النداء ملاحظة عن عملية، مش إذن لتنفيذ تعليمات غير مرتبطة موجودة في الحمولة.

راجع من غير ما تحوّل السجلات لمخزن أسرار

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

لا تنشر المخرجات إلا عند وجودها

إطلاق API العام لازم يشمل مستند OpenAPI بنسخة موثقة وتعليمات المصادقة وأمثلة أخطاء وعملية إيقاف تدريجي. أي CLI مستقبلي أو حزمة Python أو عميل TypeScript أو سيرفر MCP محتاج إصدار فعلي وchecksums ووثائق محدّثة. حزمة تجهيز KoalaVPS أو نقطة إدارة إنتاج مش بتتصدر من خلال الموقع ده.

شوية وضوح أكتر.