Как это работает
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: удаление;
- исходящей почте: сохранение и отправка тестового письма;
- уровню журнала.
Переименованные поля ответов
Поле, которое раньше говорило «да» или «нет» о том, что может быть и неизвестным, теперь называет случаи:
| Где | Поле | Значения |
|---|---|---|
| Использование диска аккаунтом | backing | enforced, notEnforced, unmeasured |
| Версии PHP | defaultStatus | default, notDefault, unknown |
| Модули | state | enabled, locked |
| Панель управления | audience | administrator, customer |
| FTPS-сервер | tlsEnforcement | enforced, notEnforced, notObserved |
Отчёт о состоянии больше не содержит поле status верхнего уровня; читайте записи об агенте и базе данных.
Чем это не является
Это не способ выполнять команды на сервере. Ничто в API не доходит до агента иначе как одной из типизированных операций, которые агент и так принимает. Это тот же закрытый набор, которым ограничена сама панель. Вызывающий не может попросить шелл, потому что на той стороне нет ничего, что его бы дало.
Ошибки говорят ровно то, что вызывающему позволено знать
Ресурс аккаунта, от имени которого вызывающий не действует, отвечает не найдено, а не запрещено. «Запрещено» подтвердило бы, что он существует, а этого вызывающий знать не вправе.
Создание одной и той же базы дважды сообщает, что она есть, и оставляет рабочим первый пароль. Повтор после потерянного ответа не должен обнулять учётные данные, которые клиенту уже показали один раз. Такие детали всплывают только в продакшене и только на чужом клиенте.
Эндпоинт, не объявивший правила доступа, закрыт для клиентов, а не открыт им. Анонимный вызывающий получает отказ 401, вошедший клиент получает 403 с пустым телом, и допускается только администратор. То же верно для пути, которому не соответствует ни один эндпоинт: клиент получает там 403, а не 404. Каждый эндпоинт называет своё правило явно; это умолчание существует на случай ошибки, а не как режим, на который стоит полагаться.
Все коды ошибок
Каждый отказ содержит стабильный машинный code рядом с фразой на языке вызывающего. Полный список
с HTTP-статусом каждого кода есть на странице Коды ошибок API.