یک توکن، ساختهشده در پنل مشتری
بهصورت یک توکن bearer ارسال میشود. در صورت تمایل میتوان آن را به فقطخواندنی یا به یک سرویس مشخص محدود کرد؛ توکنها مستقل از رمز عبور هستند و ابطال یکی هرگز خروج از سیستم را به همراه ندارد.
یک توکن برای API، و هر کاری که پنل انجام میدهد
JSON روی HTTPS. نیازی به SDK نیست، نیازی به حساب کاربری جداگانه برای توسعهدهنده نیست، و نقطه پایانیای که در پنل باشد ولی اینجا نباشد، وجود ندارد.
ایجاد سرور
curl -X POST https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN" \
-d '{"plan":"reef","image":"debian-13"}'بلافاصله یک شناسه فرآیند ساخت بازمیگرداند. دستگاه حدود 60 ثانیه بعد از طریق SSH پاسخ میدهد، و آدرس پیش از ارسال اطلاعات ورود مسیریابی میشود.
20 نقطه پایانی
همهچیز، در پنج گروه
URL پایه https://api.vpsoffshore.com/v1. در مسیر نسخهبندی میشود؛ v1 تا زمانیکه v2 وجود دارد کار خواهد کرد و تاریخ توقف آن یک سال پیشتر اعلام خواهد شد.
سرورها
GET
/servers
هر سرویس روی حساب، همراه با وضعیت، طرح و آدرسها.
POST
/servers
یکی بسازید. بلافاصله همراه با شناسه ساخت بازمیگردد؛ سرور حدود یک دقیقه بعد در دسترس است.
GET
/servers/{id}
یک سرویس، شامل مصرف زنده منابع طی یک ساعت گذشته.
PATCH
/servers/{id}
طرح را تغییر دهید. در جایی که دیسک اجازه دهد، بدون نصب مجدد تغییر اندازه میدهد.
DELETE
/servers/{id}
آن را نابود کنید. دیسکها به مدت 14 روز نگه داشته میشوند و سپس پیش از واگذاری مجدد پاک میشوند.
POST
/servers/{id}/actions
reboot · shutdown · start · rebuild · rescue · reset-password.
فضای ذخیرهسازی
GET
/servers/{id}/snapshots
اسنپشاتهای یک سرویس، جدیدترین در ابتدا.
POST
/servers/{id}/snapshots
یک اسنپشات گرفته میشود؛ سبک است، پس سریع است و فضای دیسک را دوبرابر نمیکند.
POST
/snapshots/{id}/restore
بازیابی در همان محل، یا روی سرویس دیگری با همان طرح یا طرحی بزرگتر.
DELETE
/snapshots/{id}
حذف یک اسنپشات.
شبکه
GET
/servers/{id}/addresses
آدرسهای مسیریابیشده به یک سرویس، نسخه 4 و 6.
POST
/servers/{id}/addresses
درخواست یک آدرس اضافه، یا یک /29.
PUT
/addresses/{ip}/rdns
تنظیم DNS معکوس. ظرف یک دقیقه اعمال میشود، نه در بازآوری بعدی زون.
GET
/servers/{id}/bandwidth
شمارندههای انتقال. صرفاً اطلاعاتی — سقفی برای عبور از آن وجود ندارد.
کاتالوگ
GET
/plans
هر طرح به همراه مشخصات و قیمت آن. همان منبعی که این سایت از روی آن ساخته میشود.
GET
/images
تصاویر و ISOهای در دسترس، از جمله موارد بارگذاریشده.
POST
/images
بارگذاری ISO از طریق URL. بوت همراه با کنسول متصل.
صورتحساب
GET
/invoices
صورتحسابها، پرداختشده و معوق، همراه با ارز و تراکنش زنجیره.
POST
/invoices/{id}/pay
صدور نشانی پرداخت برای یکی از 8 ارز پذیرفتهشده.
GET
/credits
جبران خسارتهای SLA اعمالشده، همراه با حادثهای که هرکدام را ایجاد کرده است.
هرآنچه پنل میتواند انجام دهد، اینجا هم هست، و چیزی اینجا نیست که در پنل نباشد. اگر این دو با هم مغایرت داشته باشند، یک باگ است — از طریق پنل اطلاع داده شود تا رفع شود، نه اینکه بهعنوان رفتار عمدی مستند شود.
نحوه عملکرد آن
چهار تصمیم که ظرف یک ساعت متوجه آنها میشوید
یک API بر اساس مسیرهای بد آن قضاوت میشود، نه مسیرهای خوبش. سه مورد از چهار مورد زیر درباره اتفاقی است که هنگام بروز خطا رخ میدهد.
ورودی JSON، خروجی JSON، بدون نیاز به SDK
HTTPS ساده، بدون پاکت سفارشی، بدون بازگشت به XML و بدون تشریفات امضا. هرچه با curl قابل انجام باشد، یک کلاینت هم برایش وجود دارد. کتابخانههای رسمی برای Go، Python و TypeScript موجود است و هیچکدام الزامی نیست.
محدودیت نرخی که تصادفاً به آن نمیرسید
600 درخواست در دقیقه به ازای هر توکن، و 60 درخواست برای فراخوانیهای ایجاد. هر پاسخ بودجهٔ باقیمانده را در یک هدر حمل میکند و در صورت عبور از آن، کد 429 به همراه تعداد ثانیههای لازم برای انتظار بازگردانده میشود — هرگز بهصورت بیصدا رد نمیشود.
خطاهایی که میگویند چه باید کرد
یک پاسخ 4xx شامل یک کد قابلخواندن توسط ماشین، یک جمله قابلفهم برای انسان، و فیلد مقصر است. ترجیح میدهیم خطایی طولانی برگردانیم تا خطایی کوتاه که باید حدس بزنید.
دو چیزی که فقط یکبار نوشته میشود
احراز هویت، و شکل یک خطا
هر دو ارزش خواندن پیش از نوشتن نخستین فراخوانی را دارند، نه پس از نخستین شکست.
احراز هویت
curl https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN"توکنها در پنل ساخته میشوند و میتوانند به حالت فقطخواندنی یا به یک سرویس محدود شوند. این توکنها مستقل از رمز عبور هستند، و لغو یکی از آنها باعث خروج از هیچ نشستی نمیشود.
محدودیت نرخ را بخوانید
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 41روی هر پاسخ، نه فقط روی آن پاسخی که با شکست مواجه میشود. عبور از سقف مجاز، کد 429 را همراه با تعداد ثانیههای لازم برای انتظار برمیگرداند؛ هرگز یک قطع بیصدا و هرگز یک پاسخ کوتاهشده.
خطا فیلد را مشخص میکند
{"error":"plan_unknown",
"message":"No plan named 'reff'. Did you mean 'reef'?",
"field":"plan"}یک کد قابلخواندن توسط ماشین، یک جمله قابلفهم برای انسان و فیلدی که خطا در آن است. خطاهای طولانی ارزانتر از خطاهای کوتاهی هستند که باید حدس زده شوند.
استعلام وضعیت ساخت
curl https://api.vpsoffshore.com/v1/servers/$ID \
-H "Authorization: Bearer $TOKEN" | jq .stateمیرود از building → running. نیازی به ثبت webhook پیش از ایجاد چیزی نیست، و polling با فاصله یک ثانیه در محدوده مجاز باقی میماند.
چیزی برای درخواست دادن نیست
توکن در پنل مشتری است، و پنل همراه نخستین سرور شما فراهم میشود
بدون حساب توسعهدهنده، بدون تأیید، و بدون محیط آزمایشی که رفتاری متفاوت از محیط عملیاتی داشته باشد.
در ادامه بخوانید
از اینجا به کجا برویم