Один токен, створений у панелі
Надсилається як bearer-токен. За бажанням обмежте його лише читанням або одним сервісом; токени не пов'язані з вашим паролем, а відкликання одного з них ніколи не завершує вашу сесію.
Один токен, і все, що вміє панель
JSON поверх HTTPS. Без потреби в SDK, без окремого облікового запису розробника і без жодної кінцевої точки, яка існує в панелі, але не тут.
Створити сервер
curl -X POST https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN" \
-d '{"plan":"reef","image":"debian-13"}'Одразу повертає ідентифікатор конфігурації. Машина відповідає по SSH приблизно за шістдесят секунд, і адреса маршрутизується ще до відправлення облікових даних.
20 кінцевих точок
Усе — у п'яти групах
Базова URL-адреса https://api.vpsoffshore.com/v1. Версія вказана в шляху; v1 продовжує працювати, коли з'явиться v2, а дату припинення підтримки буде оголошено за рік наперед.
Сервери
GET
/servers
Кожна послуга на обліковому записі — зі станом, тарифом та адресами.
POST
/servers
Створення відбувається миттєво: у відповідь одразу приходить ідентифікатор конфігурації (build id), а сервер стає доступним приблизно за хвилину.
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
Адреси, маршрутизовані до сервісу, v4 та v6.
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, перш ніж щось створювати, а опитування раз на секунду вкладається в ліміт.
Нічого не потрібно подавати
Токен — у панелі, а панель постачається разом із першим сервером
Без облікового запису розробника, без погодження, без пісочниці, що поводиться інакше, ніж продакшн.