API داده هات

با API داده هات می‌توانید منابع پروژه‌ی خود مانند سرورها، کانتینرها، والیوم‌ها و شبکه را از طریق اسکریپت، ابزارهای CI/CD یا هر برنامه‌ی دیگری مدیریت کنید. هر کاری که در پنل کاربری انجام می‌دهید، از جمله ساخت، تغییر و حذف منابع، از طریق API نیز قابل انجام است.

نشانی پایه

تمام درخواست‌های API به نشانی زیر ارسال می‌شوند و مسیر هر اندپوینت به انتهای آن اضافه می‌شود:

text

https://api.dadehat.com/api/v1

درخواست‌ها و پاسخ‌ها در قالب JSON هستند و ارتباط فقط از طریق HTTPS برقرار می‌شود.

احراز هویت

برای استفاده از API به یک توکن API نیاز دارید. توکن را در پنل کاربری، از منوی «امنیت» و بخش «توکن‌ها» بسازید و در هر درخواست، در سرآیند Authorization ارسال کنید:

text

Authorization: Bearer <TOKEN>

هر توکن به یک پروژه وابسته است و فقط به منابع همان پروژه و در محدوده‌ی دسترسی‌هایی (Scope) که هنگام ساخت انتخاب کرده‌اید، دسترسی دارد. برای جزئیات بیش‌تر، راهنمای احراز هویت در API را ببینید.

نمونه‌ی درخواست

برای دریافت فهرست سرورهای پروژه، از دستور زیر استفاده کنید:

bash

curl -H "Authorization: Bearer <TOKEN>" \
  "https://api.dadehat.com/api/v1/vms?project_id=<PROJECT_ID>"

پاسخ نمونه:

json

{
  "success": true,
  "data": [
    {
      "id": "1e2d3c4b-5a69-4f78-8e9d-0c1b2a3f4e5d",
      "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "web-01",
      "status": "running",
      "cpu_cores": 2,
      "memory_mb": 4096,
      "disk_gb": 40
    }
  ]
}

در این نمونه برخی فیلدهای پاسخ برای خوانایی حذف شده‌اند.

ساختار پاسخ

پاسخ اندپوینت‌های منابع ساختار یکسانی دارد. پاسخ مسیر /actions ساختار ویژه‌ی خود را دارد که در راهنمای عملیات‌ها (Actions) آمده است.

فیلدهای پاسخ منابع:

success: در صورت موفقیت درخواست true و در غیر این صورت false است.
data: داده‌ی پاسخ؛ یک شیء یا فهرستی از اشیا.
error: در صورت بروز خطا، توضیح خطا برای انسان.
code: کد ماشینی خطا، مانند not-found یا insufficient-scope.

json

{"success": false, "error": "token lacks the required scope", "code": "insufficient-scope"}

نکته

پیشنهاد می‌شود در برنامه‌ی خود، خطاها را بر اساس کد وضعیت HTTP و مقدار code بررسی کنید و به متن error وابسته نباشید؛ متن خطا ممکن است در آینده تغییر کند.

خواندن و تغییر منابع

عملیات در API داده هات به دو دسته تقسیم می‌شوند:

خواندن منابع: با درخواست‌های GET روی مسیر هر منبع انجام می‌شود؛ مانند GET /vms یا GET /volumes/<VOLUME_ID>. پاسخ این درخواست‌ها بلافاصله برگردانده می‌شود.
ساخت، تغییر و حذف منابع: بیش‌تر این کارها، مانند ساخت سرور یا اتصال والیوم، زمان‌بر هستند و به‌شکل «عملیات» (Action) انجام می‌شوند. شما یک عملیات را با POST /actions آغاز می‌کنید و پیشرفت آن را دنبال می‌کنید. برای جزئیات، راهنمای عملیات‌ها (Actions) را ببینید.

برخی منابع مانند کلیدهای SSH، گروه‌های امنیتی، رجیستری، فضای ابری، قوانین بیلد و زمان‌بندی اسنپ‌شات مستقیم با درخواست‌های POST، PUT، PATCH و DELETE روی مسیر خودشان مدیریت می‌شوند. فهرست کامل اندپوینت‌ها در مرجع اندپوینت‌ها آمده است.

پیگیری لحظه‌ای با WebSocket

علاوه بر پرس‌وجوی دوره‌ای وضعیت عملیات، می‌توانید با اتصال WebSocket به نشانی wss://api.dadehat.com/api/v1/ws تغییرات عملیات‌ها را به‌شکل لحظه‌ای دریافت کنید. روش اشتراک در این اتصال در راهنمای عملیات‌ها (Actions) توضیح داده شده است.

کدهای وضعیت HTTP

کد	معنا
200 / 201	درخواست با موفقیت انجام شد یا عملیات آغاز شد.
400	ورودی درخواست نامعتبر است (کد invalid_input).
401	توکن ارسال نشده، نامعتبر، منقضی یا باطل شده است، یا این مسیر با توکن در دسترس نیست.
402	سرویس به‌دلیل کمبود موجودی کیف پول معلق است و ساخت منبع جدید ممکن نیست.
403	توکن دسترسی لازم را ندارد (insufficient-scope) یا حساب سازنده‌ی توکن احراز هویت نشده است (kyc_not_verified).
404	منبع وجود ندارد یا متعلق به پروژه‌ی دیگری است.
409	درخواست با وضعیت فعلی منبع سازگار نیست؛ مانند لغو عملیاتی که پایان یافته است.
429	تعداد درخواست‌ها بیش از حد مجاز است؛ کمی صبر کنید و دوباره تلاش کنید.

یادداشت

توجه داشته باشید که درخواست برای منبعی که در پروژه‌ی دیگری قرار دارد، دقیقاً مانند منبعی که وجود ندارد با کد 404 پاسخ داده می‌شود. اگر برای شناسه‌ای که از وجود آن مطمئن هستید 404 دریافت کردید، ابتدا بررسی کنید که توکن به کدام پروژه وابسته است.

بخش‌هایی که با توکن در دسترس نیستند

بخش‌های مربوط به حساب کاربری فقط از طریق پنل کاربری و با ورود به حساب در دسترس هستند و توکن API، صرف‌نظر از دسترسی‌های آن، به آن‌ها راه ندارد:

کیف پول، پرداخت‌ها و تراکنش‌ها
احراز هویت (KYC)
تیکت‌های پشتیبانی
اعلان‌ها
گزارش رخدادها

قیمت‌ها

فهرست به‌روز نرخ منابع از مسیر GET /pricing قابل دریافت است. این اطلاعات برای محاسبه‌ی هزینه‌ی منابع پیش از ساخت آن‌ها کاربرد دارد. برای آشنایی با نحوه‌ی محاسبه‌ی هزینه‌ها، راهنمای مدل پرداخت و صورتحساب را ببینید.