Базы
Флаги баз на сервере и их владельцы.
Каждый флаг базы на сервере и его владелец — список с пагинацией и одна база по её flag id.
Идентификация базы
Эндпоинт детали принимает числовой сегмент {id} — flag id базы. Это положительное целое
без ведущих нулей (шаблон ^[1-9]\d*$); значения вроде 0 и 007 отклоняются с
400 validation_error.
GET /v1/bases
GET /v1/bases/5Авторизация
| Скоуп | Даёт |
|---|---|
bases:read | Оба эндпоинта баз — список и деталь. |
Каждый owner базы несёт discord_id (null, если владелец не привязан к Discord). Ключ без
скоупа получает 403 insufficient_scope.
GET /v1/bases
Список баз с пагинацией. Необязательные фильтры:
| Параметр | Значение |
|---|---|
owner_steam_id | Базы этого Steam64 (только цифры). |
owner_discord_id | Базы игрока, привязанного к этому Discord id (только цифры). Резолвится в момент запроса; непривязанный id ничего не находит (пустая страница, не 404). |
owner_name | Точное совпадение имени персонажа владельца (в грамматике фильтров мода нет оператора подстроки). |
min_elements / max_elements | Границы числа установленных элементов. |
min_health / max_health | Границы средней прочности элементов по шкале 0.0–1.0 (например, 0.5 = 50 %). |
search | Текстовый поиск. Нельзя сочетать со структурным фильтром выше (400 validation_error). |
limit | Размер страницы, 10–100 (по умолчанию 50). |
cursor | Непрозрачный курсор из next_cursor предыдущего ответа. |
Передать оба owner_steam_id и owner_discord_id — 400 validation_error.
Возвращает конверт коллекции. total — число баз, подходящих под запрос (по всем страницам):
{
"data": [
{
"flag_id": 5, "base_id": 2,
"owner": { "profile_id": 7, "name": "Bob", "steam_id": "76561198000000000", "discord_id": "123456789012345678" },
"max_elements": 100, "element_count": 40, "avg_health": 0.875,
"position": { "x": 1.5, "y": 2.5, "z": 3.5 }
}
],
"has_more": false,
"next_cursor": null,
"total": 1
}Про поля
owner — вложенный объект идентичности { profile_id, name, steam_id, discord_id }; discord_id
— null, если владелец не привязан. avg_health и каждая ось position — дробные числа;
avg_health в теле — 0.0–1.0 (фильтры min_health/max_health берут ту же шкалу 0.0–1.0).
GET /v1/bases/{id}
Одна база по её flag id. Возвращает тот же объект, что и строка списка. 404 not_found, если базы
с таким flag id нет.
Кэширование
Каждое чтение базы отдаёт ETag и Cache-Control: private с коротким max-age (15 с); верните
ETag в If-None-Match, чтобы получить 304 Not Modified.
Ошибки
Стандартный конверт ошибки. Самые вероятные:
| Код | Статус | Когда |
|---|---|---|
insufficient_scope | 403 | У ключа нет bases:read. |
not_found | 404 | Ни одна база не подходит под {id}. |
validation_error | 400 | {id} не положительное целое без ведущих нулей (^[1-9]\d*$), ?search= вместе со структурным фильтром, оба owner id сразу или нецифровой owner_steam_id/owner_discord_id. |
server_unavailable | 503 | Игровой сервер офлайн или недоступен. |
gateway_timeout | 504 | Сервер не ответил вовремя. |