مبانی وب سرویس

همه وب سرویس‌های آریانت REST روی HTTPS هستند، JSON می‌گیرند و برمی‌گردانند و با توکن Bearer احراز هویت می‌شوند. این صفحه قواعد مشترک و تفاوت‌های هر محصول را یک‌جا نشان می‌دهد تا کلاینت شما برای همه درست کار کند.

آدرس‌ها و نسخه‌ها

وب سرویس	آدرس پایه	سند OpenAPI
ابر آریانت	`https://api.ariaservice.net/cloud/v1`	`openapi.json`
سرور مجازی (VPS)	`https://api.ariaservice.net/api/v1`	`openapi.yaml`
VPS منطقه‌ای	`https://api.ariaservice.net/vps/v1`	`openapi.json`
هاستینگ	`https://api.ariaservice.net/hosting/v1`	`openapi.json`
سرور اختصاصی	`https://api.ariaservice.net/baremetal/v1`	`openapi.json`
پیامک	`https://api.ariaservice.net/sms/v1`	`openapi.json`

نسخه در مسیر آمده است (v1). کلاینت را طوری بنویسید که فیلدهای ناشناخته پاسخ را نادیده بگیرد؛ فیلدها و مقدارهای تازه بدون تغییر نسخه اضافه می‌شوند.

درخواست و پاسخ

بدنه درخواست‌های POST، PUT و PATCH JSON است و هدر Content-Type: application/json می‌خواهد.
زمان‌ها به UTC و در قالب ISO 8601 / RFC 3339 هستند (2026-10-02T09:30:00Z).
شناسه‌ها عدد صحیح هستند، مگر جایی که صفحه محصول خلافش را بگوید (مثلاً شماره فاکتور و شناسه پیامک متن هستند).
PATCH فقط فیلدهای ارسال‌شده را تغییر می‌دهد.

شکل پاسخ موفق در دو خانواده متفاوت است:

ابر، VPS منطقه‌ای، هاستینگ، اختصاصی، پیامک
VPS (/api/v1)

{ "data": { "id": 12, "name": "web-1" } }

{ "success": true, "data": { "id": 4821, "status": "active" } }

خطاها

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

وب سرویس	قالب خطا
ابر	`{"error": "...", "code": "not_found", "reason": "..."}`؛ `reason` در صورت وجود حالت را دقیق‌تر می‌کند
VPS منطقه‌ای، هاستینگ، سرور اختصاصی	`{"error": "...", "code": "not_found"}`
پیامک	`{"code": "not_found", "message": "..."}`
VPS (`/api/v1`)	`{"success": false, "error": {"code": "NOT_FOUND", "message": "..."}}`

معنی وضعیت‌های HTTP در همه یکسان است:

HTTP	معنی	تکرار؟
`400` / `422`	ورودی نادرست، یا درخواست درست است اما الان قابل انجام نیست	خیر؛ درخواست را اصلاح کنید
`401`	توکن نیست یا نامعتبر است	خیر
`402`	موجودی کیف پول کافی نیست	پس از شارژ
`403`	دسترسی کافی نیست	خیر
`404`	منبع در حساب شما وجود ندارد	خیر
`409` / `423`	وضعیت منبع الان اجازه نمی‌دهد یا منبع درگیر عملیات دیگری است	بله، کمی بعد
`429`	محدودیت نرخ	بله، پس از `Retry-After`
`500` / `502` / `503`	خطای موقت سمت سرور	بله، با فاصله رو به افزایش
`504`	پاسخ به‌موقع نرسید؛ ممکن است درخواست اجرا شده باشد	اول وضعیت را بخوانید

فهرست کامل codeهای هر وب سرویس در صفحه همان محصول و در سند OpenAPI آن آمده است.

محدودیت نرخ

وب سرویس	محدودیت
ابر	۶۰ درخواست در دقیقه و ۳۶۰۰ در ساعت برای هر حساب و کاربر
VPS (`/api/v1`)	خواندن ۱۲۰ در دقیقه؛ نوشتن حدود ۲۰ در دقیقه؛ ساخت سرور ۵ در ساعت برای هر توکن (جزئیات)
VPS منطقه‌ای، هاستینگ، سرور اختصاصی، پیامک	برای هر فراخواننده؛ مقدار فعلی در هدرهای `RateLimit-*`

وب سرویس‌های جدید در هر پاسخ این هدرها را می‌فرستند:

هدر	معنی
`RateLimit-Limit`	تعداد درخواست مجاز در پنجره فعلی
`RateLimit-Remaining`	درخواست‌های باقی‌مانده
`RateLimit-Reset`	ثانیه تا شروع پنجره بعدی

پس از عبور از حد، پاسخ 429 است و هدر Retry-After (بر حسب ثانیه) می‌گوید چقدر صبر کنید.

تکرار درخواست

خطاهای 429، 502، 503 و خطای شبکه را با فاصله رو به افزایش (exponential backoff) تکرار کنید و Retry-After را اگر بود رعایت کنید. درخواست‌هایی را که پول خرج می‌کنند فقط با کلید ایدمپوتنسی تکرار کنید.

Python
bash

import os
import random
import time
import requests

RETRY = {429, 502, 503}

def call(method, url, **kwargs):
    headers = {"Authorization": f"Bearer {os.environ['ARIANET_TOKEN']}", **kwargs.pop("headers", {})}
    for attempt in range(6):
        resp = requests.request(method, url, headers=headers, timeout=30, **kwargs)
        if resp.status_code not in RETRY:
            return resp
        wait = float(resp.headers.get("Retry-After", 2 ** attempt))
        time.sleep(wait + random.random())
    return resp

for attempt in 1 2 3 4 5; do
  code=$(curl -s -o /tmp/out.json -w '%{http_code}' "$URL" -H "Authorization: Bearer $ARIANET_TOKEN")
  case "$code" in
    429|502|503) sleep $((2 ** attempt)) ;;
    *) break ;;
  esac
done
cat /tmp/out.json

CLI خواندن‌هایی را که به محدودیت نرخ بخورند خودش تکرار می‌کند؛ تغییرات را هرگز خودکار تکرار نمی‌کند.

صفحه‌بندی

وب سرویس	پارامترها	اطلاعات صفحه در پاسخ
ابر	`page`، `per_page` (۱ تا ۱۰۰، پیش‌فرض ۲۵)؛ بدون این دو، کل فهرست در یک صفحه	`meta.pagination`: `page`، `per_page`، `previous_page`، `next_page`، `last_page`
پیامک	`page`، `per_page` (حداکثر ۲۰۰)	`meta`: `total`، `current_page`، `per_page`
VPS (`/api/v1`)	`page`، `limit` (۱ تا ۱۰۰، پیش‌فرض ۱۵)	`pagination`: `current_page`، `per_page`، `total`، `last_page`
VPS منطقه‌ای، هاستینگ، سرور اختصاصی	فهرست‌ها کامل برمی‌گردند؛ فهرست actionها `limit` می‌گیرد	-

عملیات ناهمگام

کاری که زمان می‌برد (ساخت، حذف، نصب مجدد، تغییر پلن، روشن و خاموش کردن) بلافاصله پاسخ 201 یا 202 می‌دهد و در پس‌زمینه انجام می‌شود. پایان آن را این‌طور دنبال کنید:

وب سرویس	چه چیزی را بررسی کنید	وضعیت نهایی
ابر	`GET /actions/{id}` با `action_id` پاسخ	`status`: `success` یا `error`
VPS منطقه‌ای، هاستینگ	`GET /actions/{id}`	`state`: `success` یا `error`
سرور اختصاصی	`GET /orders/{id}` (مراحل تحویل)	سفارش تحویل‌شده یا لغوشده
پیامک	`GET /batches/{id}` یا وب‌هوک	`completed`، `partial` یا `failed`
VPS (`/api/v1`)	`GET /servers/{id}/status` یا `GET /servers/{id}/actions`	`status` برابر `active` / action با `success` یا `failed`

هر چند ثانیه یک بار بررسی کنید (مثلاً هر ۵ ثانیه) و برای کل انتظار سقف زمانی بگذارید. CLI با --wait و actions wait همین کار را انجام می‌دهد.

تکرار امن (ایدمپوتنسی)

اگر پاسخ سفارشی به دست شما نرسد (قطع شبکه، 504)، نمی‌دانید سفارش ثبت شده یا نه. با کلید ایدمپوتنسی می‌توانید همان درخواست را بی‌خطر دوباره بفرستید: سفارش دوم ساخته نمی‌شود و پاسخ اول برمی‌گردد.

وب سرویس	درخواست‌ها	چطور
VPS (`/api/v1`)	`POST /servers`	هدر `Idempotency-Key` اجباری (جزئیات)
VPS منطقه‌ای	`POST /servers`	هدر `Idempotency-Key`
هاستینگ	`POST /accounts`	هدر `Idempotency-Key`
سرور اختصاصی	`POST /orders`، `POST /servers/{id}/renew`	هدر `Idempotency-Key`
پیامک	`POST /messages`	فیلد `client_reference` (یا هدر `Idempotency-Key`)

برای هر سفارش تازه یک کلید تازه (مثلاً UUID) بسازید و تا گرفتن پاسخ قطعی همان را برای تکرارها نگه دارید.

curl -s -X POST https://api.ariaservice.net/vps/v1/servers \
  -H "Authorization: Bearer $ARIANET_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"datacenter":"thr-1","plan_id":4,"image":"ubuntu-24.04","hostname":"web-1","billing_mode":"hourly"}'

ریجن‌ها

VPS منطقه‌ای و هاستینگ در هر ریجن نصب جداگانه دارند. ریجن را با هدر Arianet-Region انتخاب کنید؛ بدون آن، درخواست به ریجن پیش‌فرض محصول می‌رود:

curl -s https://api.ariaservice.net/hosting/v1/accounts \
  -H "Authorization: Bearer $ARIANET_TOKEN" \
  -H "Arianet-Region: iran-1"

ریجن ناشناخته پاسخ 404 region_not_found می‌گیرد. پیامک فقط در iran-1 اجرا می‌شود و سرور اختصاصی یک نصب دارد؛ هیچ‌کدام به این هدر نیاز ندارند.

سقف زمان پاسخ و 504

درخواست‌هایی که به ریجن دیگری می‌روند ممکن است با 504 gateway_timeout تمام شوند، در حالی که خود کار انجام شده باشد. پیش از تکرار، وضعیت را بخوانید (فهرست منابع یا actionها) یا از کلید ایدمپوتنسی استفاده کنید.

آدرس‌ها و نسخه‌ها​

درخواست و پاسخ​

خطاها​

محدودیت نرخ​

تکرار درخواست​

صفحه‌بندی​

عملیات ناهمگام​

تکرار امن (ایدمپوتنسی)​

ریجن‌ها​

سقف زمان پاسخ و 504​