Перейти к содержимому

Как это работает

API провижининга

Как биллинговая система создаёт, приостанавливает, меняет тариф и удаляет хостинг-аккаунты без участия человека и как интеграция аутентифицируется сегодня.

Maran задуман так, чтобы на нём продавали хостинг, а значит система, которая берёт деньги, должна уметь им управлять. Панель, которой можно управлять только руками, требует человека за каждым действием.

Пока вход, а не ключ

Биллинг аутентифицируется сегодня как вход: он входит через POST /api/v1/auth/login и передаёт полученный токен доступа как bearer-токен. Токен живёт недолго (по умолчанию 15 минут) и обновляется через POST /api/v1/auth/refresh. Жизненный цикл аккаунта ниже требует входа администратора, поэтому заведите интеграции собственный вход, а не человека: так её сессии можно завершать отдельно, а её вызовы различимы в журнале аудита.

Ключей API с ограниченной областью, которые позволяли бы заводить аккаунты, ни до чего больше не дотягиваясь, пока нет. Пока их нет, вход интеграции несёт весь доступ администратора, а каждый сделанный им вызов попадает в журнал аудита рядом со всем, что сделал человек.

Жизненный цикл аккаунта

ВызовЧто происходит на сервере
СоздатьЗаводит системного пользователя, его дом и квоту тарифа, затем записывает аккаунт
ПриостановитьОстанавливает сайты и входы, сохраняя всё остальное: это состояние, а не удаление
Изменить тарифПереносит квоту, бюджет воркеров и лимиты на новый тариф
УдалитьУбирает базы, логины и jail, завершает процессы аккаунта, затем убирает пользователя, прерываясь, а не оставляя сирот

Вызовы: POST /api/v1/accounts, POST /api/v1/accounts/{id}/suspend (и /reactivate), PUT /api/v1/accounts/{id}/plan и DELETE /api/v1/accounts/{id}. Каждый из них выполняет ту же операцию, что и собственные экраны панели. Второго, более слабого пути для машин нет: API и интерфейс вызывают один и тот же код, поэтому они не могут разойтись в том, что означает приостановка.

Функции тарифов, аккаунты и просмотры

Создание и изменение тарифа требуют список features, то есть полный набор функций, которые продаёт тариф; при изменении он заменяет прежний. Пустой список не включает ни одной функции, а запрос без списка отклоняется. GET /api/v1/plans/features перечисляет доступные функции (только администратор).

Несколько эндпоинтов обслуживают собственные экраны панели и перечислены здесь для полноты:

ЭндпоинтКтоНазначение
GET /api/v1/dashboard/attention-countАдминистраторСколько вещей требует внимания
GET /api/v1/serversАдминистраторУправляемые серверы; одна запись вида local
GET /api/v1/me/accountsКлиентАккаунты, которыми владеет вход
POST /api/v1/me/active-accountКлиентПереключить активный аккаунт, тело {accountId}
GET, POST, DELETE /api/v1/me/pinned-pagesВошедший пользовательЧитать, добавлять и убирать избранные страницы
/api/v1/me/sub-usersВладелец аккаунтаПриглашать, менять и удалять участников команды
POST, GET, DELETE /api/v1/view-asАдминистраторНачать, читать и завершить просмотр как аккаунт

Ответы без тела

Изменение, которому нечего сообщить, отвечает 204 No Content без тела. Раньше оно отвечало 200 с телом true, которое не сообщало вызывающему ничего сверх кода статуса. Клиент, разбиравший тело, должен прекратить это делать; клиент, проверяющий успех, должен принимать любой код 2xx. Это относится к:

  • идентификации: выход, смена пароля, завершение сессий, приглашения, пользователи, политика безопасности и завершение просмотра как аккаунт;
  • тарифам и резервным копиям: удаление;
  • cron: изменение, включение или отключение, удаление и переменные окружения;
  • базам данных, сайтам и сертификатам: удаление и снятие;
  • брандмауэру: разрешение, запрет, бан, снятие бана и удаление из белого списка;
  • пользователям FTPS и SFTP: удаление;
  • исходящей почте: сохранение и отправка тестового письма;
  • уровню журнала.

Переименованные поля ответов

Поле, которое раньше говорило «да» или «нет» о том, что может быть и неизвестным, теперь называет случаи:

ГдеПолеЗначения
Использование диска аккаунтомbackingenforced, notEnforced, unmeasured
Версии PHPdefaultStatusdefault, notDefault, unknown
Модулиstateenabled, locked
Панель управленияaudienceadministrator, customer
FTPS-серверtlsEnforcementenforced, notEnforced, notObserved

Отчёт о состоянии больше не содержит поле status верхнего уровня; читайте записи об агенте и базе данных.

Чем это не является

Это не способ выполнять команды на сервере. Ничто в API не доходит до агента иначе как одной из типизированных операций, которые агент и так принимает. Это тот же закрытый набор, которым ограничена сама панель. Вызывающий не может попросить шелл, потому что на той стороне нет ничего, что его бы дало.

Ошибки говорят ровно то, что вызывающему позволено знать

Ресурс аккаунта, от имени которого вызывающий не действует, отвечает не найдено, а не запрещено. «Запрещено» подтвердило бы, что он существует, а этого вызывающий знать не вправе.

Создание одной и той же базы дважды сообщает, что она есть, и оставляет рабочим первый пароль. Повтор после потерянного ответа не должен обнулять учётные данные, которые клиенту уже показали один раз. Такие детали всплывают только в продакшене и только на чужом клиенте.

Эндпоинт, не объявивший правила доступа, закрыт для клиентов, а не открыт им. Анонимный вызывающий получает отказ 401, вошедший клиент получает 403 с пустым телом, и допускается только администратор. То же верно для пути, которому не соответствует ни один эндпоинт: клиент получает там 403, а не 404. Каждый эндпоинт называет своё правило явно; это умолчание существует на случай ошибки, а не как режим, на который стоит полагаться.

Все коды ошибок

Каждый отказ содержит стабильный машинный code рядом с фразой на языке вызывающего. Полный список с HTTP-статусом каждого кода есть на странице Коды ошибок API.