Довідник API
Використовуйте операції API та інтерпретуйте їх результати
Прочитайте доступні кінцеві точки, правила ідемпотентності, відповіді на дії в черзі та поточні обмеження на відстеження операцій.
На цій сторінці
Перш ніж почати
- Дійсна сесія та, для захищених змін, її CSRF-токен.
- Ідентифікатори, взяті з поточного каталогу або автентифікованих відповідей API.
- Унікальний ключ ідемпотентності для кожного замовлення, виведення або дії з обладнанням.
Прочитайте обліковий запис перед його зміною
Використовуйте кінцеві точки читання, щоб підтвердити обліковий запис, баланс і цільовий ресурс. GET /api/v1/me повертає username, balanceUsd і csrfToken сесії. Ідентифікатори ресурсів прив’язані до облікового запису; використовуйте ідентифікатор сервера або мережі, повернутий для поточного облікового запису, а не копіюйте значення з іншого середовища.
Поточний API — це компактний інтерфейс облікового запису, а не повна платформа асинхронних завдань. Зберігайте посилання з успішних записів у власних записах. Немає кінцевої точки для переліку всіх замовлень, перевірки конкретної дії в черзі або отримання останнього статусу перевірки виведення.
| Кінцева точка читання | Повернуті дані |
|---|---|
| GET /api/v1/ledger | Останні записи реєстру 100, спочатку найновіші; без контракту на пагінацію. |
| GET /api/v1/servers | Нетерміновані сервери, стан, регіон, paidThrough, graceUntil і autoRenew. |
| GET /api/v1/network | Призначені адреси, довжини префіксів, значення PTR та пов'язані ідентифікатори серверів. |
| GET /api/health | Базові послуги та кількість у каталозі; без гарантії стану облікового запису чи фізичного сервера. |
Використовуйте відповідну кінцеву точку зміни
Підтримувані дії сервера: reboot, power_off, reinstall, mount_iso, kvm і rotate_root_password. Власна URL-адреса ISO повинна використовувати публічний HTTPS без вбудованих облікових даних. Термін замовлення — щотижневий або щомісячний, що становить сім або тридцять днів. Ціна, знижки, кошти та потужність перевіряються сервісом; не надсилайте обчислену клієнтом ціну як авторитетну.
| Кінцева точка | Поля запиту та результат |
|---|---|
| POST /api/v1/orders | configId, regionId, osId, term, quantity; необов'язково sshPublicKey. Повертає ідентифікатор замовлення та ACCEPTED. |
| POST /api/v1/deposit-addresses | актив. Повертає адресу, актив, мережу, confirmationsRequired і режим або помилку settlement-unavailable. |
| POST /api/v1/withdrawals | актив, призначення, usd. Повертає id і PENDING_REVIEW; баланс утримується. |
| POST /api/v1/servers/{id}/actions | дія; isoUrl для mount_iso. Повертає ідентифікатор дії та QUEUED. |
| PUT /api/v1/servers/{id}/ddos | режим: BASELINE або ADVANCED. Повертає QUEUED або UNCHANGED та quoteRequired. |
| PUT /api/v1/network/{id}/rdns | ptr або порожнє значення для очищення. Повертає збережене значення PTR. |
Зробіть повторні спроби обдуманими
Замовлення, виведення коштів, дії з сервером та запити DDoS вимагають Idempotency-Key. Використовуйте 8–100 літери, цифри, дефіси або підкреслення та виділяйте новий ключ для кожної окремої запланованої операції. Збережіть оригінальний ключ, ресурс і корисне навантаження перед надсиланням, щоб можна було дослідити невизначену відповідь.
Замовлення можуть відтворити існуючий результат для того самого ключа та нормалізованого запиту; змінені деталі замовлення призводять до конфлікту. Повтори дій сервера повертають існуючу дію, якщо вона сумісна. Тримайте ключі дій унікальними для всіх серверів в обліковому записі. Виведення коштів повідомляє про конфлікт, якщо вже записано, а не повертає оригінальний запит як успіх.
POST /api/v1/servers/{serverId}/actions HTTP/1.1
Content-Type: application/json
x-csrf-token: <current-session-token>
Idempotency-Key: <unique-operation-key>
Cookie: <current-session-cookies>
{"action":"reboot"}Розрізняйте приймання та завершення
Відповідь QUEUED від 202 підтверджує, що запит на обладнання було зареєстровано. Вона не містить робочої URL-адреси KVM, нового root-пароля або доказу перезавантаження машини. Так само ACCEPTED фіксує замовлення, що переходить до етапу підготовки; PENDING_REVIEW фіксує виведення коштів, яке очікує на перевірку оператором. Зберігайте повернутий ідентифікатор, коли запитуєте про виконання.
У цій версії немає маршруту опитування статусу дії. Повторно прочитайте дані сервера або мережі, де це доречно, та отримайте підтвердження оператора для фізичних ефектів. Збережений PTR або перевага DDoS самі по собі не є вимірюванням публічного DNS або живого захисту мережі.
Реагуйте на збої без дублювання роботи
- Помилка перевірки 400: виправте задокументовані поля перед повторним надсиланням.
- 401 або 403: виправте автентифікацію сеансу або перевірку CSRF перед повторною спробою.
- 404: перевірте, що ідентифікатор ресурсу належить обліковому запису, який увійшов.
- 409: перевірте код помилки; недостатній баланс, вичерпана ємність і конфлікти ідемпотентності потребують різних відповідей.
- 502 або 503 на депозитах: не повернуто придатної нової адреси; не ініціюйте переказ.
- Тайм-аут або нечитабельна відповідь: перевірте наявні записи облікового запису та збережіть деталі оригінального запиту. Не створюйте сліпо новий ключ операції.