Один токен, создаётся в панели
Передаётся как bearer-токен. При желании ограничьте его только чтением или одной услугой; токены не зависят от вашего пароля, а отзыв одного из них никогда не завершает вашу сессию.
Один токен — и всё, что умеет панель
JSON поверх HTTPS. Не нужен SDK, не нужен отдельный аккаунт разработчика, и нет ни одного endpoint, который существовал бы в панели, но не здесь.
Создать сервер
curl -X POST https://api.havenvps.com/v1/servers \
-H "Authorization: Bearer $TOKEN" \
-d '{"plan":"reef","image":"debian-13"}'Сразу возвращает id сборки. Машина отвечает по SSH примерно через шестьдесят секунд, а адрес маршрутизируется ещё до отправки учётных данных.
20 эндпоинтов
Всё, в пяти группах
Базовый URL https://api.havenvps.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.havenvps.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.havenvps.com/v1/servers/$ID \
-H "Authorization: Bearer $TOKEN" | jq .stateПереходит из building → running. Регистрировать webhook перед созданием чего-либо не нужно, а опрос раз в секунду укладывается в лимит.
Не нужно ничего запрашивать
Токен — в панели, а панель прилагается к первому серверу
Не нужен аккаунт разработчика, не нужно одобрение, нет песочницы, которая ведёт себя иначе, чем продакшн.