پرش به مطلب اصلی

وب سرویس خدمات آریانت

راهنمای کامل API برای پلتفرم ابری آریانت. تمام نقاط پایانی احراز‌شده نیاز به توکن API دارند.

شروع سریع​

1. دریافت توکن API​

# با پشتیبانی تماس بگیرید یا از داشبورد برای تولید توکن استفاده کنید
# آن را در هدر درخواست به عنوان قرار دهید: Authorization: Bearer YOUR_TOKEN

2. اولین درخواست خود را ارسال کنید​

curl -X GET "https://api.arianet.io/api/v1/balance" \
  -H "Authorization: Bearer YOUR_TOKEN"

3. فهرست سرورهای خود​

curl -X GET "https://api.arianet.io/api/v1/servers" \
  -H "Authorization: Bearer YOUR_TOKEN"

مرور احراز هویت​

API آریانت از احراز هویت توکن Bearer استفاده می‌کند. توکن API خود را در هدر Authorization قرار دهید:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

دریافت توکن شما​

  1. وارد داشبورد آریانت شوید
  2. به تنظیمات → توکن‌های API بروید
  3. روی تولید توکن جدید کلیک کنید
  4. توکن را کپی کنید و به طور ایمن ذخیره کنید (فقط یک بار نمایش داده می‌شود!)

بهترین روش‌های امنیتی توکن​

  • هرگز توکن‌ها را در کد سمت کلاینت یا کنترل نسخه‌ای قرار ندهید
  • از متغیرهای محیطی برای ذخیره توکن‌ها در تولید استفاده کنید
  • توکن‌ها را به طور منظم تجدید کنید تا قطع‌ابی را کاهش دهید
  • توکن‌های جداگانه برای برنامه‌های مختلف یا محیط‌های مختلف ایجاد کنید
  • از لیست‌های IP برای محدود کردن استفاده توکن بر اساس IP منبع استفاده کنید

محدودیت نرخ​

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

دسته‌بندیحدپنجرهنکته
عمومی100 درخواست15 دقیقهمناطق، نقشه‌های قیمت، قالب‌های OS (احراز هویت مورد نیاز نیست)
عملیات خواندن100 درخواست15 دقیقهنقاط پایانی GET برای سرورها، موجودی، توکن‌ها
عملیات نوشتن1000 درخواست15 دقیقهPOST، PUT، DELETE برای ایجاد/ویرایش منابع

هدرهای محدودیت نرخ:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 1693478400

هنگامی که محدودیت نرخ فعال شود، پاسخ 429 Too Many Requests دریافت می‌کنید. تعطیل‌های نمایی برای تلاش مجدد پیاده‌سازی کنید.

مدیریت خطا​

تمام خطا‌ها از یک فرمت JSON سازگار پیروی می‌کنند:

{
  "error": "INVALID_REQUEST",
  "message": "پیام خطای تفصیلی",
  "status": 400
}

کدهای وضعیت متداول​

کدمعنیاقدام
200موفقدرخواست با موفقیت انجام شد
201ایجاد شدمنبع با موفقیت ایجاد شد
400درخواست نامعتبرفرمت درخواست و پارامترها را بررسی کنید
401غیر مجازتوکن API معتبر و منقضی نشده را تأیید کنید
403ممنوعشما اجازه دسترسی به این منبع ندارید
404یافت نشدمنبع وجود ندارد یا حذف شد
429درخواست‌های بیش از حدمحدودیت نرخ تجاوز شد، قبل از تلاش مجدد منتظر بمانید
500خطای سروربعداً دوباره امتحان کنید، اگر ادامه یافت با پشتیبانی تماس بگیرید

اشیای رایج پاسخ​

این نمونه‌ها شکل آبجکت‌هایی را نشان می‌دهند که داخل پاسخ‌های API برگردانده می‌شوند. مرجع اصلی، نمونه پاسخ هر endpoint است.

کاربر​

خروجی GET /api/v1/auth/me درون data.

{
  "id": 12345,
  "email": "user@example.com",
  "mobile": "+1234567890",
  "status": "active",
  "verified": true
}

سرویس (سرور)​

خروجی endpointهای فهرست و جزئیات سرور درون data.

{
  "id": 98765,
  "hostname": "web-server-1",
  "status": "active",
  "instance_status": "running",
  "datacenter": {
    "id": 1,
    "name": "us-east-1",
    "display_name": "US East (N. Virginia)"
  },
  "plan": {
    "id": 1,
    "name": "Standard 2GB"
  },
  "os": {
    "id": 5,
    "name": "Ubuntu 22.04 LTS"
  },
  "ip_addresses": [
    {
      "ip": "192.168.1.10",
      "type": "primary"
    }
  ],
  "protected": false,
  "cycle": "monthly",
  "created_at": "2024-01-15T10:30:00Z"
}

کیف پول (موجودی)​

خروجی GET /api/v1/balance درون data.

{
  "id": 1,
  "balance": 150.5,
  "primary": true,
  "status": "active",
  "currency": {
    "id": 1,
    "code": "USD",
    "name": "US Dollar",
    "symbol": "$"
  }
}

تراکنش​

خروجی GET /api/v1/balance/transactions درون data.transactions[].

{
  "id": 5001,
  "type": "debit",
  "amount": 29.99,
  "description": "Monthly server charge - web-server-1",
  "created_at": "2024-01-20T08:15:00Z"
}

گروه طرح​

خروجی GET /api/v1/plans/datacenter/{datacenter_id} درون data.groups[].

{
  "id": 10,
  "name": "Standard Plans",
  "plans": [
    {
      "id": 1,
      "name": "Standard 2GB",
      "display_name": "Standard 2GB",
      "recommended": false,
      "cycle": "monthly",
      "cpu": {
        "size": 1,
        "unit": "vCPU"
      },
      "ram": {
        "size": 2,
        "unit": "GB"
      },
      "storage": {
        "size": 20,
        "unit": "GB"
      },
      "prices": [
        {
          "code": "USD",
          "currency": "$",
          "hourly": "0.05",
          "monthly": "29.99",
          "yearly": "299.90"
        }
      ]
    }
  ]
}

طرح​

خروجی GET /api/v1/plans/{id} درون data.

{
  "id": 1,
  "name": "Standard 2GB",
  "display_name": "Standard 2GB",
  "recommended": false,
  "cycle": "monthly",
  "cpu": {
    "size": 1,
    "unit": "vCPU"
  },
  "ram": {
    "size": 2,
    "unit": "GB"
  },
  "storage": {
    "size": 20,
    "unit": "GB"
  },
  "prices": [
    {
      "code": "USD",
      "currency": "$",
      "hourly": "0.05",
      "monthly": "29.99",
      "yearly": "299.90"
    }
  ]
}

منطقه (مرکز داده)​

خروجی GET /api/v1/regions درون data.regions[].

{
  "id": 1,
  "name": "us-east-1",
  "display_name": "US East (N. Virginia)",
  "country": "US"
}

الگوی سیستم‌عامل​

خروجی GET /api/v1/os/datacenter/{datacenter_id} درون data.operating_systems[].

{
  "id": 5,
  "name": "Ubuntu 22.04 LTS",
  "category": "Linux"
}

توکن API​

خروجی GET /api/v1/auth/tokens درون data.tokens[].

{
  "id": 1,
  "name": "CLI Token",
  "prefix": "arr_abc123...",
  "last_used": "2024-01-20T15:30:00Z",
  "expires": null,
  "created_at": "2024-01-15T10:00:00Z"
}

کلید SSH​

خروجی endpointهای کلید SSH درون data.

{
  "id": 1001,
  "name": "My Laptop",
  "fingerprint": "SHA256:AbCd+EfG...",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...",
  "created_at": "2024-01-10T14:22:00Z"
}

دیوار آتش​

خروجی endpointهای دیوار آتش درون data.

{
  "id": 2001,
  "name": "Web Server Firewall",
  "protected": false,
  "rules": [
    {
      "protocol": "tcp",
      "port": 80,
      "direction": "in",
      "cidr": "0.0.0.0/0"
    }
  ],
  "created_at": "2024-01-12T09:45:00Z"
}

احراز هویت​

دریافت اطلاعات کاربر جاری​

GET /api/v1/auth/me
Authorization: Bearer {token}

دریافت اطلاعات کاربر احراز‌شده.

پاسخ:

{
  "data": {
    "id": 12345,
    "email": "user@example.com",
    "mobile": "+1234567890",
    "status": "active",
    "verified": true
  }
}

فهرست توکن‌های API​

GET /api/v1/auth/tokens
Authorization: Bearer {token}

فهرست تمام توکن‌های API کاربر احراز‌شده.

پاسخ:

{
  "data": {
    "tokens": [
      {
        "id": 1,
        "name": "CLI Token",
        "prefix": "arr_abc123...",
        "last_used": "2024-01-20T15:30:00Z",
        "expires": null,
        "created_at": "2024-01-15T10:00:00Z"
      }
    ]
  }
}

لغو توکن​

DELETE /api/v1/auth/tokens/{id}
Authorization: Bearer {token}

لغو توکن API خاص براساس شناسه.

پارامترها:

  • id (path، ضروری): شناسه توکن

پاسخ:

{
  "data": {
    "message": "توکن با موفقیت لغو شد"
  }
}

خروج از حساب​

DELETE /api/v1/auth/logout
Authorization: Bearer {token}

لغو توکن API جاری مورد استفاده برای احراز هویت.

پاسخ:

{
  "data": {
    "message": "توکن با موفقیت لغو شد"
  }
}

سرورها (خدمات)​

فهرست سرورها​

GET /api/v1/servers?page=1&limit=15&status=active
Authorization: Bearer {token}

فهرست تمام سرورهای کاربر احراز‌شده.

پارامترهای Query:

  • page (integer، پیش‌فرض: 1): شماره صفحه برای pagination
  • limit (integer، پیش‌فرض: 15، حداکثر: 100): نتایج در هر صفحه
  • status (string، اختیاری): فیلتر براساس وضعیت (active, suspended, creating, failed, terminated, pending)

پاسخ:

{
  "data": [
    {
      "id": 98765,
      "hostname": "web-server-1",
      "status": "active",
      "instance_status": "running",
      "datacenter": {
        "id": 1,
        "name": "us-east-1",
        "display_name": "US East (N. Virginia)"
      },
      "plan": {
        "id": 1,
        "name": "Standard 2GB"
      },
      "os": {
        "id": 5,
        "name": "Ubuntu 22.04 LTS"
      },
      "ip_addresses": [
        {
          "ip": "192.168.1.10",
          "type": "primary"
        }
      ],
      "protected": false,
      "cycle": "monthly",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 15,
    "total": 42,
    "last_page": 3
  }
}

دریافت جزئیات سرور​

GET /api/v1/servers/{id}
Authorization: Bearer {token}

دریافت اطلاعات تفصیلی سرور خاص.

پارامترها:

  • id (path، ضروری): شناسه سرور

پاسخ:

{
  "data": {
    "id": 98765,
    "hostname": "web-server-1",
    "status": "active",
    "instance_status": "running",
    "datacenter": {
      "id": 1,
      "name": "us-east-1",
      "display_name": "US East (N. Virginia)"
    },
    "plan": {
      "id": 1,
      "name": "Standard 2GB"
    },
    "os": {
      "id": 5,
      "name": "Ubuntu 22.04 LTS"
    },
    "ip_addresses": [
      {
        "ip": "192.168.1.10",
        "type": "primary"
      },
      {
        "ip": "192.168.1.11",
        "type": "secondary"
      }
    ],
    "protected": false,
    "cycle": "monthly",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

دریافت وضعیت سرور​

GET /api/v1/servers/{id}/status
Authorization: Bearer {token}

بررسی سریع وضعیت سرور بدون دریافت جزئیات کامل.

پارامترها:

  • id (path، ضروری): شناسه سرور

پاسخ:

{
  "data": {
    "id": 98765,
    "status": "active",
    "instance_status": "running"
  }
}

ایجاد سرور​

POST /api/v1/servers
Authorization: Bearer {token}
Content-Type: application/json

ایجاد سرور ابری جدید.

بدنه درخواست:

{
  "datacenter_id": 1,
  "plan_id": 1,
  "os_id": 5,
  "hostname": "web-server-1",
  "project_id": null
}

پارامترها:

  • datacenter_id (integer، ضروری): شناسه مرکز داده/منطقه
  • plan_id (integer، ضروری): شناسه طرح سرور
  • os_id (integer، ضروری): شناسه الگوی سیستم‌عامل
  • hostname (string، اختیاری): نام میزبان سرور
  • project_id (integer، اختیاری): شناسه پروژه برای سازمان

پاسخ: (201 Created)

{
  "data": {
    "id": 99999,
    "hostname": "web-server-1",
    "status": "creating",
    "instance_status": "initializing",
    "datacenter": {
      "id": 1,
      "name": "us-east-1"
    },
    "plan": {
      "id": 1,
      "name": "Standard 2GB"
    },
    "os": {
      "id": 5,
      "name": "Ubuntu 22.04 LTS"
    },
    "ip_addresses": [],
    "protected": false,
    "cycle": "monthly",
    "created_at": "2024-01-21T10:30:00Z"
  }
}

راه‌اندازی مجدد سرور​

POST /api/v1/servers/{id}/restart
Authorization: Bearer {token}

اجرای بازآغازی مرتب سرور در حال اجرا.

پارامترها:

  • id (path، ضروری): شناسه سرور

پاسخ:

{
  "data": {
    "message": "راه‌اندازی مجدد سرور شروع شد"
  }
}

روشن کردن سرور​

POST /api/v1/servers/{id}/power-on
Authorization: Bearer {token}

روشن کردن سرور خاموش.

پارامترها:

  • id (path، ضروری): شناسه سرور

پاسخ:

{
  "data": {
    "message": "روشن کردن سرور شروع شد"
  }
}

خاموشی سرور​

POST /api/v1/servers/{id}/power-off
Authorization: Bearer {token}

خاموشی سرور در حال اجرا.

پارامترها:

  • id (path، ضروری): شناسه سرور

پاسخ:

{
  "data": {
    "message": "خاموشی سرور شروع شد"
  }
}

تغییر نام سرور​

POST /api/v1/servers/{id}/rename
Authorization: Bearer {token}
Content-Type: application/json

تغییر نام میزبان سرور.

پارامترها:

  • id (path، ضروری): شناسه سرور

بدنه درخواست:

{
  "hostname": "new-web-server"
}

پاسخ:

{
  "data": {
    "message": "تغییر نام سرور شروع شد"
  }
}

نصب مجدد سیستم‌عامل​

POST /api/v1/servers/{id}/reinstall
Authorization: Bearer {token}
Content-Type: application/json

نصب مجدد سیستم‌عامل روی سرور. هشدار: تمام داده‌ها حذف خواهند شد.

پارامترها:

  • id (path، ضروری): شناسه سرور

بدنه درخواست:

{
  "os_id": 6
}

پاسخ:

{
  "data": {
    "message": "نصب مجدد سیستم‌عامل شروع شد"
  }
}

تبدیل حفاظت​

POST /api/v1/servers/{id}/toggle-protection
Authorization: Bearer {token}

فعال یا غیرفعال کردن حفاظت از حذف برای سرور.

پارامترها:

  • id (path، ضروری): شناسه سرور

پاسخ:

{
  "data": {
    "protected": true,
    "message": "حفاظت سرور تبدیل شد"
  }
}

حذف سرور​

DELETE /api/v1/servers/{id}
Authorization: Bearer {token}

حذف سرور. هشدار: این کار دائمی است و تمام داده‌ها حذف خواهند شد.

پارامترها:

  • id (path، ضروری): شناسه سرور

پاسخ: (204 No Content)

کاتالوگ (نقاط پایانی عمومی - بدون احراز هویت)​

فهرست مناطق​

GET /api/v1/regions

فهرست تمام مراکز داده/مناطق دسترس‌پذیر.

پاسخ:

{
  "data": {
    "regions": [
      {
        "id": 1,
        "name": "us-east-1",
        "display_name": "US East (N. Virginia)",
        "country": "US"
      },
      {
        "id": 2,
        "name": "eu-west-1",
        "display_name": "EU West (Ireland)",
        "country": "IE"
      },
      {
        "id": 3,
        "name": "ap-southeast-1",
        "display_name": "Asia Pacific (Singapore)",
        "country": "SG"
      }
    ]
  }
}

فهرست طرح‌ها براساس مرکز داده​

GET /api/v1/plans/datacenter/{datacenter_id}

فهرست تمام طرح‌های سرور دسترس‌پذیر برای مرکز داده خاص با قیمت.

پارامترها:

  • datacenter_id (path، ضروری): شناسه مرکز داده

پاسخ:

{
  "data": {
    "groups": [
      {
        "id": 10,
        "name": "Standard Plans",
        "plans": [
          {
            "id": 1,
            "name": "Standard 2GB",
            "display_name": "Standard 2GB",
            "recommended": false,
            "cycle": "monthly",
            "cpu": {
              "size": 1,
              "unit": "vCPU"
            },
            "ram": {
              "size": 2,
              "unit": "GB"
            },
            "storage": {
              "size": 20,
              "unit": "GB"
            },
            "prices": [
              {
                "code": "USD",
                "currency": "$",
                "hourly": "0.05",
                "monthly": "29.99",
                "yearly": "299.90"
              },
              {
                "code": "EUR",
                "currency": "€",
                "hourly": "0.045",
                "monthly": "27.99",
                "yearly": "279.90"
              }
            ]
          }
        ]
      }
    ]
  }
}

دریافت جزئیات طرح​

GET /api/v1/plans/{id}

دریافت اطلاعات تفصیلی طرح خاص.

پارامترها:

  • id (path، ضروری): شناسه طرح

پاسخ:

{
  "data": {
    "id": 1,
    "name": "Standard 2GB",
    "display_name": "Standard 2GB",
    "recommended": false,
    "cycle": "monthly",
    "cpu": {
      "size": 1,
      "unit": "vCPU"
    },
    "ram": {
      "size": 2,
      "unit": "GB"
    },
    "storage": {
      "size": 20,
      "unit": "GB"
    },
    "prices": [
      {
        "code": "USD",
        "currency": "$",
        "hourly": "0.05",
        "monthly": "29.99",
        "yearly": "299.90"
      }
    ]
  }
}

فهرست سیستم‌عامل‌ها براساس مرکز داده​

GET /api/v1/os/datacenter/{datacenter_id}

فهرست تمام الگوهای سیستم‌عامل دسترس‌پذیر برای مرکز داده خاص.

پارامترها:

  • datacenter_id (path، ضروری): شناسه مرکز داده

پاسخ:

{
  "data": {
    "operating_systems": [
      {
        "id": 5,
        "name": "Ubuntu 22.04 LTS",
        "category": "Linux"
      },
      {
        "id": 6,
        "name": "Debian 12",
        "category": "Linux"
      },
      {
        "id": 7,
        "name": "CentOS 9",
        "category": "Linux"
      }
    ]
  }
}

کلید‌های SSH​

فهرست کلید‌های SSH​

GET /api/v1/ssh-keys
Authorization: Bearer {token}

فهرست تمام کلید‌های SSH در حساب کاربر احراز‌شده.

پاسخ:

{
  "data": [
    {
      "id": 1001,
      "name": "My Laptop",
      "fingerprint": "SHA256:AbCd+EfG...",
      "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...",
      "created_at": "2024-01-10T14:22:00Z"
    }
  ]
}

دریافت جزئیات کلید SSH​

GET /api/v1/ssh-keys/{id}
Authorization: Bearer {token}

دریافت جزئیات کلید SSH خاص.

پارامترها:

  • id (path، ضروری): شناسه کلید SSH

پاسخ:

{
  "data": {
    "id": 1001,
    "name": "My Laptop",
    "fingerprint": "SHA256:AbCd+EfG...",
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...",
    "created_at": "2024-01-10T14:22:00Z"
  }
}

ایجاد کلید SSH​

POST /api/v1/ssh-keys
Authorization: Bearer {token}
Content-Type: application/json

افزودن کلید SSH عمومی جدید به حساب.

بدنه درخواست:

{
  "name": "Production Key",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC..."
}

پاسخ: (201 Created)

{
  "data": {
    "id": 1004,
    "name": "Production Key",
    "fingerprint": "SHA256:AbCd+EfG...",
    "created_at": "2024-01-20T14:45:00Z"
  }
}

بروز‌رسانی کلید SSH​

PUT /api/v1/ssh-keys/{id}
Authorization: Bearer {token}
Content-Type: application/json

بروز‌رسانی فراداده کلید SSH.

پارامترها:

  • id (path، ضروری): شناسه کلید SSH

بدنه درخواست:

{
  "name": "Updated Key Name"
}

پاسخ:

{
  "data": {
    "id": 1001,
    "name": "Updated Key Name",
    "fingerprint": "SHA256:AbCd+EfG...",
    "created_at": "2024-01-10T14:22:00Z"
  }
}

حذف کلید SSH​

DELETE /api/v1/ssh-keys/{id}
Authorization: Bearer {token}

حذف کلید SSH از حساب.

پارامترها:

  • id (path، ضروری): شناسه کلید SSH

پاسخ: (204 No Content)

دیوار آتش​

فهرست دیوارهای آتش​

GET /api/v1/firewalls
Authorization: Bearer {token}

فهرست تمام گروه‌های دیوار آتش در حساب.

پاسخ:

{
  "data": [
    {
      "id": 2001,
      "name": "Web Server Firewall",
      "protected": false,
      "rules": [
        {
          "protocol": "tcp",
          "port": 80,
          "direction": "in",
          "cidr": "0.0.0.0/0"
        },
        {
          "protocol": "tcp",
          "port": 443,
          "direction": "in",
          "cidr": "0.0.0.0/0"
        }
      ],
      "created_at": "2024-01-12T09:45:00Z"
    }
  ]
}

دریافت جزئیات دیوار آتش​

GET /api/v1/firewalls/{id}
Authorization: Bearer {token}

دریافت جزئیات دیوار آتش خاص شامل تمام قوانین.

پارامترها:

  • id (path، ضروری): شناسه دیوار آتش

پاسخ:

{
  "data": {
    "id": 2001,
    "name": "Web Server Firewall",
    "protected": false,
    "rules": [
      {
        "index": 0,
        "protocol": "tcp",
        "port": 80,
        "direction": "in",
        "cidr": "0.0.0.0/0"
      },
      {
        "index": 1,
        "protocol": "tcp",
        "port": 443,
        "direction": "in",
        "cidr": "0.0.0.0/0"
      },
      {
        "index": 2,
        "protocol": "tcp",
        "port": 22,
        "direction": "in",
        "cidr": "203.0.113.0/24"
      }
    ],
    "created_at": "2024-01-12T09:45:00Z"
  }
}

ایجاد دیوار آتش​

POST /api/v1/firewalls
Authorization: Bearer {token}
Content-Type: application/json

ایجاد گروه دیوار آتش جدید.

بدنه درخواست:

{
  "name": "My Firewall"
}

پاسخ: (201 Created)

{
  "data": {
    "id": 2004,
    "name": "My Firewall",
    "protected": false,
    "rules": [],
    "created_at": "2024-01-20T14:45:00Z"
  }
}

افزودن قانون دیوار آتش​

POST /api/v1/firewalls/{id}/rules
Authorization: Bearer {token}
Content-Type: application/json

افزودن قانون جدید به دیوار آتش.

پارامترها:

  • id (path، ضروری): شناسه دیوار آتش

بدنه درخواست:

{
  "protocol": "tcp",
  "port": 80,
  "direction": "in",
  "cidr": "0.0.0.0/0"
}

پاسخ:

{
  "data": {
    "message": "قانون با موفقیت اضافه شد"
  }
}

حذف قانون دیوار آتش​

DELETE /api/v1/firewalls/{id}/rules/{rule_index}
Authorization: Bearer {token}

حذف قانون خاص از دیوار آتش.

پارامترها:

  • id (path، ضروری): شناسه دیوار آتش
  • rule_index (path، ضروری): شاخص قانون (0-based)

پاسخ: (204 No Content)

حذف دیوار آتش​

DELETE /api/v1/firewalls/{id}
Authorization: Bearer {token}

حذف تمام گروه دیوار آتش شامل تمام قوانین.

پارامترها:

  • id (path، ضروری): شناسه دیوار آتش

پاسخ: (204 No Content)

حساب و صورت‌حساب​

دریافت موجودی حساب​

GET /api/v1/balance
Authorization: Bearer {token}

دریافت موجودی حساب و اطلاعات اعتبار.

پاسخ:

{
  "data": {
    "balance": 150.50,
    "currency": "USD",
    "status": "active",
    "used_this_month": 45.25,
    "remaining": 105.25
  }
}

دریافت تاریخچه تراکنش‌ها​

GET /api/v1/balance/transactions?page=1&limit=50
Authorization: Bearer {token}

مشاهده تاریخچه تراکنش‌های حساب.

پارامترهای Query:

  • page (integer، پیش‌فرض: 1): شماره صفحه
  • limit (integer، پیش‌فرض: 50): نتایج در هر صفحه

پاسخ:

{
  "data": [
    {
      "id": 5001,
      "type": "debit",
      "amount": 29.99,
      "description": "هزینه سرور ماهانه - web-server-1",
      "date": "2024-01-20T00:00:00Z"
    },
    {
      "id": 5002,
      "type": "credit",
      "amount": 50.00,
      "description": "اعتبار حساب اعمال‌شد",
      "date": "2024-01-18T12:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 128,
    "last_page": 3
  }
}

مدیریت خطاها​

تمام پاسخ‌های API از یک قالب خطا سازگار پیروی می‌کنند:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "پیام خطای قابل‌فهم توسط انسان",
    "details": {
      "field": "زمینه اضافی"
    }
  }
}

کدهای خطای رایج​

کدوضعیت HTTPتوضیحات
INVALID_ID400فرمت شناسه منبع نامعتبر
VALIDATION_ERROR400تأیید درخواست ناموفق
UNAUTHORIZED401توکن احراز هویت موجود نیست یا نامعتبر
FORBIDDEN403مجوزهای ناکافی
NOT_FOUND404منبع یافت نشد
CONFLICT409تضاد منبع (مثلاً تکراری)
RATE_LIMIT_EXCEEDED429درخواست‌های بیش‌ازحد
INTERNAL_SERVER_ERROR500خطای سرور

محدود‌کردن نرخ​

نقاط پایانی عمومی محدود‌شده براساس IP: 100 درخواست/دقیقه نقاط پایانی احراز‌شده: 1000 درخواست/دقیقه عملیات‌های نوشتاری: 100 درخواست/دقیقه

اطلاعات محدود‌کردن نرخ در سرصحفه‌های پاسخ بازگردانی می‌شود:

  • X-RateLimit-Limit: حداکثر درخواست‌ها در این پنجره
  • X-RateLimit-Remaining: درخواست‌های باقی‌مانده
  • X-RateLimit-Reset: مهرزمان Unix هنگام تعیین‌مجدد محدودیت