مرجع REST API

Vapor مبني على فلسفة تُعطي الأولوية للـ API. كل إجراء متاح في واجهة الويب مدعوم بـ REST API شاملة وموثقة توثيقاً كاملاً.

المصادقة

يستخدم Vapor API مصادقة Bearer Token عبر JSON Web Tokens (JWT).

1. أولاً، أنشئ API Token عبر واجهة المستخدم (قائمة API Token) أو قم بالمصادقة عبر نقطة النهاية /api/v1/auth/login باستخدام اسم المستخدم وكلمة المرور.
2. أدرج الرمز المميز في ترويسة Authorization لجميع الطلبات اللاحقة:

Authorization: Bearer <your_jwt_token>

مواصفة OpenAPI

ينشر Vapor مواصفة OpenAPI 3.1.0 الكاملة الخاصة به. يمكنك الوصول إلى ملف openapi.yaml الخام من الكود المصدري أو الاستعلام عن نقطة النهاية /api/v1 (إذا كان Swagger UI مُفعّلاً في نشرك).

يغطي الـ API جميع ميزات المنصة بما في ذلك:

• إدارة نظام المضيف (/api/v1/system/*)
• الشبكات (/api/v1/network/*)
• التخزين (/api/v1/storage/*)
• الافتراضية (/api/v1/virtualization/*)
• Kubernetes (/api/v1/kubernetes/*)

رفع الملفات الكبيرة (بروتوكول TUS)

بالنسبة لنقاط النهاية التي تتطلب رفع ملفات ضخمة—مثل صور ISO للآلات الافتراضية أو صور Docker/الحاويات—يُطبّق Vapor بروتوكول TUS الإصدار 1.0.0.

TUS هو بروتوكول مفتوح لرفع الملفات القابل للاستئناف عبر HTTP. يضمن أن عمليات الرفع متعددة الغيغابايت (مثل صورة Ubuntu ISO بحجم 4 غيغابايت) يمكنها الصمود في وجه انقطاعات الشبكة دون الحاجة إلى البدء من الصفر.

نقاط نهاية TUS المدعومة

• /api/v1/virtualmachines/isos/upload/*
• /api/v1/containers/images/upload/*
• /api/v1/docker/images/upload/*

مثال على التكامل (JavaScript)

إذا كنت تبني تكاملاً مخصصاً للواجهة الأمامية، فإننا نوصي بشدة باستخدام مكتبة tus-js-client الرسمية:

import * as tus from 'tus-js-client';

const upload = new tus.Upload(file, {
  endpoint: 'https://<vapor-ip>:7770/api/v1/virtualmachines/isos/upload',
  headers: {
    'Authorization': 'Bearer ' + token
  },
  chunkSize: 10 * 1024 * 1024, // 10MB chunks
  metadata: {
    filename: file.name,
    filetype: file.type
  },
  onError: (error) => console.error('Upload failed:', error),
  onProgress: (bytesUploaded, bytesTotal) => {
    const percentage = ((bytesUploaded / bytesTotal) * 100).toFixed(2);
    console.log(`${percentage}% uploaded`);
  },
  onSuccess: () => {
    console.log('Upload complete');
    // Call the finalization endpoint
    fetch(`/api/v1/virtualmachines/isos/upload/${upload.url.split('/').pop()}/complete`, {
      method: 'POST',
      headers: { 'Authorization': 'Bearer ' + token }
    });
  }
});

upload.start();

لمزيد من التفاصيل حول بروتوكول TUS، تفضل بزيارة tus.io.

عرض مرجع API الكامل

توثيق API التفاعلي الكامل يُولَّد ديناميكياً ويمكن الاطلاع عليه هنا:

عرض مرجع Vapor REST API