REST API

В XenForo 2.1 был добавлен REST API. Это позволяет вам программно взаимодействовать со многими областями установки XenForo.

Для доступа к API необходимо сгенерировать ключ через панель управления администратора. Доступ к API без аутентификации отсутствует, и в настоящее время пользователи не могут генерировать свои собственные ключи для доступа к API.

API для конкретной установки XenForo доступен по адресу <XenForo base URL>/api/. Все конечные точки имеют префикс этого URL. Например, если XenForo установлен по адресу https://example.com/community/, тогда URL-адреса API будут начинаться с https://example.com/community/api/. В этом примере доступ к списку потоков будет осуществляться через https://example.com/community/api/threads/.

API включен по умолчанию. При необходимости весь доступ к API можно быстро отключить, добавив в src/config.php следующее:

$config['enableApi'] = false;

Ключи API

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

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

Типы ключей

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

Для управления этим существует три типа ключей API:

Guest key - этот ключ всегда обращается к API как гостевой пользователь. Эти запросы всегда будут учитывать гостевые разрешения. Например, если гости не могут отвечать в темах, запрос API на ответ в теме приведет к ошибке отсутствия разрешения.
User key - этот ключ всегда обращается к API как указанный пользователь и всегда учитывает разрешения этого пользователя, аналогично гостевому ключу.
Super user key - этот ключ может получить доступ к API как любой пользователь, передав ему дополнительное значение. При желании этот ключ может обходить разрешения запрашивающего пользователя, позволяя им выполнять действия или просматривать контент, к которому у них обычно нет доступа.

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

Области видимости ключа

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

Каждая конечная точка в API будет охвачена одной или несколькими областями. Если API не предоставлена ни одна из этих областей, запрос не будет выполнен.

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

Доступ к API

Как только вы узнаете URL-адрес для доступа к API и получите ключ, вы можете начать делать запросы к нему.

Все ответы API будут возвращены в формате JSON, за исключением случаев, когда двоичный файл запрашивается специально (например, при загрузке вложения). Ошибки всегда возвращают код ответа в диапазоне 400. Успешные запросы вернут код 200. Редиректы обычно не используются, но возвращают код из 300 диапазонов.

Тела запросов должны отправляться в кодировке application/x-www-form-urlencoded или, если файл загружается, в кодировке multipart/form-data. Параметры также могут передаваться через строку запроса, хотя для запросов, не связанных с GET, мы настоятельно рекомендуем передавать параметры через тело запроса.

Все данные запроса должны использовать набор символов UTF-8.

Запросы должны передавать ключ API для использования через заголовок XF-Api-Key. Это должно присутствовать во всех запросах.

Если выбранный ключ API является ключом суперпользователя, вы можете передать идентификатор пользователя контекста через заголовок XF-Api-User. Если идентификатор пользователя не передан, контекст по умолчанию будет гостевым.

Если запрос выполняется с помощью ключа суперпользователя, и вы хотите обойти разрешения контекстного пользователя, это можно сделать для каждого запроса, установив для параметра api_bypass_permissions значение 1. (Это можно передать через строку запроса или как часть тела запроса.)

Обработка ошибок

При обнаружении ошибки код ответа будет в диапазоне 400. Иногда может возникать ошибка диапазона 500, хотя это указывает на то, что сервер не смог обработать запрос. API может быть временно отключен или произошла другая ошибка сервера.

Сообщения об ошибках имеют стандартный формат. Вот пример:

{
    "errors": [
        {
            "code": "api_key_not_found",
            "message": "Ключ API, указанный в запросе, не найден.",
            "params": []
        }
    ]
}

Верхним уровнем будет объект с ключом errors. Это будет массив с 1 или более записями. Каждая запись представляет собой объект со следующими параметрами:

code - это машиночитаемый код ошибки. Существует много возможных кодов ошибок, поскольку они зависят от ситуации.
message - удобочитаемая версия ошибки. Это может измениться или может быть переведено, и его не следует использовать для определения типа ошибки.
params - это список параметров ключ-значение, относящихся к сработавшей ошибке. Они могут дополнять код ошибки и сообщение, чтобы дать более подробную информацию об ошибке.

Конечные точки API

API имеет ряд конечных точек и действий, которые можно предпринять. Дополнительные конечные точки и данные могут быть добавлены в будущем.

Смотрите документацию по конечной точке API

Эта документация по конечной точке была создана на основе данных API и комментариев в коде. Со временем он будет расширяться и обновляться.