API

  • Просмотры Просмотры: 1,226
  • Последнее обновление Последнее обновление:

Навигация

API
   Конечные точки
   Типы данных
Страница

  • Contents

    REST API​

    На форуме присутствует REST API, которое почти полностью соответствует официальному API XenForo (см. источник).
    Это позволяет программно взаимодействовать со многими, доступными вам, областями форума [BROKENCORE].

    Для доступа к API требуется создать ключ в панели пользователя. Неавторизованный доступ к API отсутствует.

    API форума доступен по адресу https://brokencore.club/api/. Все конечные точки имеют префикс этого URL-адреса.

    Например, доступ к списку тем будет осуществляться по адресу https://brokencore.club/api/threads/

    Ключи API​

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

    Типы ключей​

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

    Доступ к API​

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

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

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

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

    В каждом запросе должен присутствовать ключ API в заголовке XF-Api-Key.
    Каждый user-agent запроса должен содержать в себе BrokenAPI

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

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

    Сообщения об ошибках имеют стандартный формат. Вот пример:
    JSON: 
    {
    
    "errors": [
    
        {
    
            "code": "api_key_not_found",
    
            "message": "API key provided in request was not found.",
    
            "params": []
    
        }
    
    ]
    
}
    Верхним уровнем будет объект с ключом errors. Это будет массив с 1 или более записями. Каждая запись представляет собой объект со следующими параметрами:
    • code - это машиночитаемый код ошибки. Существует много возможных кодов ошибок, поскольку они зависят от ситуации.
    • message - удобочитаемая версия ошибки. Может измениться; не следует использовать для определения типа ошибки.
    • params - это список параметров «ключ-значение», относящихся к сработавшей ошибке. Они могут дополнять код ошибки и сообщение, чтобы дать более подробную информацию об ошибке.

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

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