Запросы, ответы и ошибки

Базовый адрес API Guard Forum:

https://forum.arzguard.com/api/

Путь метода добавляется после /api/. Например, GET threads/ вызывается по адресу https://forum.arzguard.com/api/threads/; номер страницы можно добавить как ?page=1.

Список тем GET threads/ содержит threads и pagination. Структура успешного ответа зависит от метода и прав доступа.

Формат запроса

Все передаваемые данные используют UTF-8. Ключ авторизации обязателен в каждом запросе:

XF-Api-Key: YOUR_API_KEY
Accept: application/json

YOUR_API_KEY — условное обозначение. Подробнее о типах ключей и контексте пользователя — на странице «Авторизация».

Ситуация	Как передавать параметры
GET-запрос	В query string после `?`
Запрос с обычным телом	`application/x-www-form-urlencoded`
Загрузка файла	`multipart/form-data`

XenForo также допускает параметры в query string у запросов с телом, но рекомендует передавать их в теле. Выбор метода и список допустимых параметров определяет конкретный endpoint.

JSON — формат обычного ответа API. Для тела запроса используйте форму: application/x-www-form-urlencoded либо multipart/form-data. Не подменяйте их application/json.

В JavaScript обычную форму можно подготовить через URLSearchParams, а форму с файлом — через FormData. При использовании FormData клиент должен самостоятельно сформировать заголовок с boundary; не задавайте Content-Type вручную без этой границы.

Ответы и HTTP-статусы

Обычные ответы возвращаются в JSON. Исключение — методы, явно запрашивающие бинарный файл, например скачивание вложения: такой ответ нужно обрабатывать как файл, а не через response.json().

HTTP	Значение	Действие клиента
`200`	Запрос выполнен успешно	Разобрать ответ по схеме метода
`3xx`	Перенаправление	Проверить конечный адрес и правила перенаправлений клиента
`4xx`	Ошибка запроса или доступа	Разобрать `errors` и исправить причину
`5xx`	Сервер не смог обработать запрос	Обработать сбой отдельно от ошибок параметров

Стандартный успешный ответ XenForo использует HTTP 200. Не определяйте успех по наличию единого поля вроде success: структура успешного ответа зависит от метода. Для инфраструктурного сбоя обработчик должен учитывать ситуацию, когда JSON разобрать не удалось. Например, ответ внешнего прокси может отличаться от стандартного тела ошибки XenForo.

Структура ошибки

Стандартный ответ XenForo содержит массив errors с одной или несколькими ошибками. Ниже — условный пример ошибки неизвестного ключа:

{
  "errors": [
    {
      "code": "api_key_not_found",
      "message": "API key provided in request was not found.",
      "params": []
    }
  ]
}

Поле	Для чего использовать
`errors`	Перечень ошибок запроса; обрабатывайте все элементы
`errors[].code`	Машиночитаемый код для логики приложения
`errors[].message`	Текстовое описание для человека
`errors[].params`	Дополнительные параметры ошибки; набор зависит от причины, может быть пустым

Текст message может меняться или переводиться. Для распознавания ситуации используйте code, а HTTP-статус сохраняйте как отдельную характеристику. Единого исчерпывающего списка кодов для всех ситуаций нет: они зависят от метода и причины ошибки.

Пример запроса на чтение

Оба примера обращаются к GET threads/; ключу нужен scope thread:read. Они предназначены для серверного окружения с заранее настроенной переменной FORUM_API_KEY. Примеры не содержат реального ключа и не включают обход прав пользователя.

cURL
Node.js

curl --silent --show-error \
  --header "XF-Api-Key: $FORUM_API_KEY" \
  --header 'Accept: application/json' \
  'https://forum.arzguard.com/api/threads/?page=1'

По умолчанию cURL выведет тело ответа, в том числе JSON ошибки. Для диагностики HTTP-статуса можно добавить --write-out '\nHTTP %{http_code}\n'. Не включайте вывод заголовков запроса с ключом в публичные логи.

const apiKey = process.env.FORUM_API_KEY;
if (!apiKey) throw new Error('Не задана FORUM_API_KEY');

const response = await fetch('https://forum.arzguard.com/api/threads/?page=1', {
  headers: {
    'XF-Api-Key': apiKey,
    Accept: 'application/json'
  },
  redirect: 'error'
});

let data;
try {
  data = await response.json();
} catch {
  throw new Error(`HTTP ${response.status}: ответ не является JSON`);
}

if (!response.ok) {
  const codes = Array.isArray(data.errors)
    ? data.errors.map(error => error.code).filter(Boolean)
    : [];
  throw new Error(`HTTP ${response.status}: ${codes.join(', ') || 'ошибка API'}`);
}

const threads = data.threads;
const pagination = data.pagination;
// Используйте threads и pagination в своей серверной интеграции.

Здесь перенаправления намеренно отключены, а диагностическое сообщение содержит HTTP-статус и коды ошибок без ключа и полного тела ответа. Ошибки сети или отклонённого перенаправления обрабатываются вызывающим кодом.

Пагинация

Пагинация зависит от метода. Если ответ содержит pagination, обрабатывайте страницы по её метаданным и описанию endpoint. Не считайте параметр page или поле pagination обязательными для любого списка. В постраничных ответах pagination содержит current_page, last_page, per_page, shown и total. При пустой коллекции текущая и последняя страницы могут быть 0. Если запрошенная страница выходит за пределы непустой выдачи, API возвращает ошибку invalid_page с параметром max.

Обработку HTTP и errors удобно вынести в общий клиент. Схему успешного ответа и правила пагинации оставьте на уровне конкретного метода: они различаются.

Авторизация

Ключи, scopes и права пользователя, от имени которого работает интеграция.

Контракт REST API XenForo

Официальное руководство по форматам запросов, ответов и ошибок.

Общая информация

Guard Forum

Kalenich Stats

Запросы, ответы и ошибки

Формат запроса

Ответы и HTTP-статусы

Структура ошибки

Пример запроса на чтение

Пагинация

Авторизация

Контракт REST API XenForo

​Формат запроса

​Ответы и HTTP-статусы

​Структура ошибки

​Пример запроса на чтение

​Пагинация

Авторизация

Контракт REST API XenForo

Формат запроса

Ответы и HTTP-статусы

Структура ошибки

Пример запроса на чтение

Пагинация