قراردادهای API

نشانی پایه و قالب

همهٔ نقاط پایانی زیر مسیر /api و روی همان میزبان داشبورد هستند، مثلاً https://veneshcloud.ir/api. درخواست و پاسخ JSON است. هدر Accept: application/json را بفرستید و اگر بدنه دارید Content-Type: application/json را هم.

احراز هویت

کلید API خود را به‌صورت Authorization: Bearer <key> بفرستید. نقاط پایانی که در مرجع عمومی علامت خورده‌اند به کلید نیاز ندارند. کلید نبودن یا ابطال‌شده بودن 401 می‌دهد.

خطاها

بدنهٔ خطا شامل message است. خطاهای اعتبارسنجی یک شیء errors هم دارند که برای هر فیلد فهرستی از پیام‌ها را می‌دهد.

زبان

هدر Accept-Language: fa یا en را بفرستید تا پیام‌های خطا به فارسی یا انگلیسی بیایند. هر مقدار دیگری به انگلیسی برمی‌گردد. فقط متن تغییر می‌کند، نه ساختار.

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

ساخت ماشین و عملیات روی آن زمان می‌برد؛ پس API سریع پاسخ می‌دهد و کار در پس‌زمینه تمام می‌شود.

1. عملیات را صدا بزنید، مثلاً POST /orders/{order}/actions/stop. با 202 و ماشین در وضعیت در جریان، مثلاً stopping، پاسخ می‌دهد.
2. هر چند ثانیه GET /orders/{order} را بپرسید.
3. وقتی وضعیت یکی از وضعیت‌های پایدار بود توقف کنید: running، stopped، failed یا terminated.

وضعیت‌های در جریان: pending، provisioning، starting، stopping، rebooting، resizing، reinstalling، restoring و deleting. اگر ماشین به failed رسید، failure_reason دلیل را می‌گوید.

تغییرات شبکهٔ خصوصی و استقرار اپلیکیشن‌ها با فیلدهای وضعیت خودشان از همین الگو پیروی می‌کنند.

مبالغ و فهرست‌ها

مبالغ برای نمایش به ریال و در فیلدهایی هستند که با _rial تمام می‌شوند. نقاط پایانی فهرست per_page می‌پذیرند و فهرست‌های صفحه‌بندی‌شده کنار data یک شیء meta برمی‌گردانند.

صفحه‌های مرتبط

هر صفحهٔ مرجع همهٔ فیلدها و یک نمونهٔ curl را نشان می‌دهد؛ از نمای کلی توسعه‌دهندگان شروع کنید.