Skip to content

Latest commit

 

History

History
360 lines (301 loc) · 27.9 KB

workshop.md

File metadata and controls

360 lines (301 loc) · 27.9 KB
Raw

Мастерская

В API мастерской находятся методы, позволяющие просматривать, создавать, изменять и удалять работы. Одним словом CRUD.

GET /workshop

Возвращает список доступных к просмотру работ в мастерской.

Query параметры

Имя Описание Тип данных Стандартное значение
take Количество работ на одной странице. number 20
page Запрашиваемая страница. number 0
search Фрагмент названия/описания/id/имени автора для поиска. string ""
filters Список категорий, которые должны иметь возвращаемые работы. Передаются id категорий через запятую без пробела. string (array) ""
sort Требуемый порядок сортировки. О возможных значениях ниже string ""

Возможные значения для параметра сортировки:

  • relevant_up — Сначала наиболее актуальные.
  • popular_up — Сначала с наибольшим количеством звёзд.
  • date_up — Сначала более новые.
  • name_up — Сортировка по алфавиту.

Особенности

Note

Данный эндпоинт не требует обязательной аутентификации, однако токен сессии, переданный в cookies будет учтён при составлении списка работ. Подробнее об этом ниже.

Если работа имеет категорию, имеющую параметр only_admins = true или если работа имеет доступ только по ссылке, а так же если автор работы заблокирован на сайте, то она исключается из списка работ, возвращаемых этим эндпоинтом.

Note

Если пользователь имеет право ManageBandages или является супер админом, то модификаторы доступа игнорируются. Так же если пользователь с такими правами запросит работы с категориями, имеющими параметры only_admins = true, передав id этих категорий в query параметре filters, то вышеописанные правила так же проигнорируются и бекенд вернет такие работы.

Возвращаемое значение

Массив, состоящий из объектов повязки.

Поле Описание Тип данных
id Внутренний инкрементальный id повязки в базе данных. number
external_id Внешний id повязки. Используется в URL. string
title Заголовок повязки. string
description Описание повязки. string | null
base64 Изображение повязки в формате Base 64. Префикс data:image/png;base64, не передается. string
split_type Показывает, используются ли разные изображения для разных типов рук. boolean
creation_date Время создания повязки. Date as string
stars_count Количество пользователей, добавивших повязку в избранное number
starred Если передан токен авторизации, то параметр показывает, добавлена ли данная повязка у текущего пользователя в избранное. В ином случае всегда равно false. boolean
author Профиль автора повязки. Об этом ниже. Author
categories Массив категорий повязки. Об этом ниже. Category[]

Объект автора повязки

О пользователях подробнее в другом разделе.

Поле Описание Тип данных
id Id пользователя. string
name Глобальное имя пользователя. string
username Имя пользователя для URL. string
public Является ли профиль пользователя публичным. boolean

Объект категории

Поле Описание Тип данных
id id категории. number
name Название категории. string
icon Ключ иконки категории. string
Пример JSON ответа 
{
"data": [
    {
        "id": 69,
        "external_id": "coolid",
        "title": "Повязка",
        "description": "Описание",
        "base64": "Base 64",
        "split_type": false,
        "creation_date": "2023-07-26T15:55:00.000Z",
        "stars_count": 1,
        "starred": false,
        "author": {
            "id": "69",
            "name": "AndcoolSystems",
            "username": "andcoolsystems",
            "public": true
        },
        "categories": [
            {
                "id": 0,
                "name": "Официальные",
                "icon": "IconRosetteDiscountCheck"
            },
            {
                "id": 6,
                "name": "Тематические",
                "icon": "IconBrush"
            }
        ]
    }
],
"totalCount": 41,
"next_page": 2
}

POST /workshop

Strict Auth required
Создает новую работу в мастерской.

Note

Данный эндпоинт доступен только авторизованным пользователям!

Все повязки, создаваемые пользователем, автоматически получают категорию На проверке, которая исключает её из мастерской до момента удаления. Один пользователь может иметь только 5 одновременных повязок на проверке! Общих ограничений по количеству нет.

Тело запроса

Поле Описание Тип данных Обязательный Ограничения
base64 Повязка в формате Base 64. string Да -
base64_slim Повязка в формате Base 64 для тонких рук. Обрабатывается только в случае, когда split_type равен split_type string Нет -
title Заголовок повязки string Да Длина от 1 до 50 символов
description Описание повязки string Нет Длина до 300 символов
categories Массив id категорий number[] Да -
split_type Использовать ли разные повязки для разных типов рук. Делает параметр base64_slim обязательным boolean Нет -

Особенности

Если параметр split_type равен true, то поле base64_slim должно быть представлено в теле запроса. Так же в таком случае изображения повязок должны быть равны по высоте.

По умолчанию на повязку всегда применяется категория На проверке, независимо от переданных категорий в теле запроса. Так же все категории проходят валидацию, где несуществующие или недоступные для установки категории (у которых reachable равен true) игнорируются.

Любая повязка должна иметь ширину в 16 пикселей и чётную высоту от 2 до 24.

Возвращаемое значение

При удачном создании повязки, сервер вернёт HTTP код 201 и тело ответа:

Поле Описание Тип данных
external_id Внешний id повязки string
statusCode Дублирует HTTP Status Code number

GET /workshop/<external_id>

Получить объект повязки.
Доступ к этому эндпоинту можно получить только передав Unique-Access хедер в запрос, содержащий токен доступа. Токен не разглашается.

Возвращаемое значение

Поле Описание Тип данных
id Внутренний инкрементальный id повязки в базе данных. number
external_id Внешний id повязки. Используется в URL. string
title Заголовок повязки. string
description Описание повязки. string | null
base64 Изображение повязки в формате Base 64. Префикс data:image/png;base64, не передается. string
base64_slim Изображение повязки для тонких рук. Передаётся только если split_type равен true. string | undefined
split_type Показывает, используются ли разные изображения для разных типов рук. boolean
creation_date Время создания повязки. Date as string
stars_count Количество пользователей, добавивших повязку в избранное number
starred Если передан токен авторизации, то параметр показывает, добавлена ли данная повязка у текущего пользователя в избранное. В ином случае всегда равно false. boolean
author Профиль автора повязки. Об этом ниже. Author
categories Массив категорий повязки. Об этом ниже. Category[]
me_profile Привязанный к текущему пользователю Minecraft профиль. Об этом ниже. Profile | undefined
permissions_level Уровень доступа при редактировании. number
access_level Общий уровень доступа к повязке в мастерской. number
check_state Этап проверки повязки. string | null

permissions_level показывает, какие действия пользователь может совершать с повязкой:

  • 0 — Пользователь не является владельцем повязки, а так же админом.
  • 1 — Пользователь является владельцем повязки, но она уже прошла модерацию. (Об этом подробнее в разделе редактирования повязок). У него есть доступ к удалению, изменению категорий и уровня доступа.
  • 2 — Пользователь является админом с ролью ManageBandages или владельцем повязки во время модерации. Возможно совершать любое действие с повязкой.

access_level показывает, кто и как может получить доступ к повязке:

  • 0 — Доступ имеют только владелец и администраторы с правом ManageBandages
  • 1 — Доступ есть у всех, у кого есть ссылка. В мастерской эта повязка не видна.
  • 2 — Повязка отображается в мастерской.

check_state показывает этап проверки повязки модерацией:

  • 'under review' — Повязка сейчас проходит модерацию.
  • 'denied' — Повязка отклонена.
  • null — Повязка прошла модерацию.

Объект Minecraft профиля

Поле Описание Тип данных
uuid UUID профиля Minecraft. string
nickname Никнейм профиля Minecraft string

Профиль передается только в том случае, когда он подключён к аккаунту и в настройках включена автозагрузка скина в мастерской.

Пример JSON ответа 
{
  "statusCode": 200,
  "data": {
      "id": 69,
      "external_id": "coolid",
      "title": "Повязка",
      "description": "Описание",
      "base64": "base64",
      "split_type": false,
      "creation_date": "2023-07-26T15:55:00.000Z",
      "stars_count": 1,
      "starred": false,
      "author": {
          "id": "1",
          "name": "AndcoolSystems",
          "username": "andcoolsystems",
          "public": true
      },
      "categories": [
          {
              "id": 0,
              "name": "Официальные",
              "icon": "IconRosetteDiscountCheck"
          },
          {
              "id": 6,
              "name": "Тематические",
              "icon": "IconBrush"
          }
      ],
      "me_profile": {
          "uuid": "1420c63cb1114453993fb3479ba1d4c6",
          "nickname": "AndcoolSystems"
      },
      "permissions_level": 2,
      "access_level": 2,
      "check_state": null
  }
}

GET /workshop/<external_id>/info

Возвращает основную информацию о повязке. Используется для генерации Open Graph.
Доступ к этому эндпоинту можно получить только передав Unique-Access хедер в запрос, содержащий токен доступа. Токен не разглашается.

Возвращаемое значение

Поле Описание Тип данных
id Внутренний инкрементальный id повязки в базе данных. number
external_id Внешний id повязки. Используется в URL. string
title Заголовок повязки. string
description Описание повязки. string | null
stars_count Количество пользователей, добавивших повязку в избранное number
average_og_color Средний цвет повязки в формате HEX string
author Профиль автора повязки. Об этом ниже. Author
Пример JSON ответа 
{
  "statusCode": 200,
  "data": {
      "id": 69,
      "external_id": "coolid",
      "title": "Повязка",
      "description": "Описание",
      "average_og_color": "#b46691",
      "stars_count": 1,
      "author": {
          "id": "1",
          "name": "AndcoolSystems",
          "username": "andcoolsystems",
          "public": true
      }
  }
}

GET /workshop/<external_id>/og

GET /workshop/<external_id>/as_image (Deprecated)
Content-Type: image/png
Возвращает изображение повязки в формате png.

Query параметры

Имя Описание Тип данных Стандартное значение
width Ширина повязки. Минимальный размер 16, максимальный 1024. Должен целочисленно делиться на 16 number 512

GET /categories

Возвращает список категорий.

Query параметры

Имя Описание Тип данных Стандартное значение
for_edit Показывает, должен ли бекенд возвращать категории, доступные только для применения при создании, а не для поиска. boolean false

Возвращаемое значение

Возвращает массив объектов, типа Category

Пример JSON ответа 
[
  {
      "id": 0,
      "name": "Официальные",
      "icon": "IconRosetteDiscountCheck"
  },
  {
      "id": 3,
      "name": "Окрашиваемые",
      "icon": "IconPalette"
  }
]

PUT /star/<external_id>

Strict Auth required
Добавляет/удаляет повязку в избранное.

Query параметры

Имя Описание Тип данных
set Добавить или удалить повязку из избранного. boolean

PUT /workshop/<external_id>

Strict Auth required
Обновляет повязку.

Тело запроса

Поле Описание Тип данных Обязательный Ограничения
title Заголовок повязки. string Да Длина от 1 до 50 символов
description Описание повязки string Нет Длина до 300 символов
categories Массив id категорий. number[] Нет -
access_level Уровень доступа к повязке. number Нет -

Особенности

Во время проверки повязки её владелец имеет равные с администратором права на ее редактирование. После одобрения повязки, её владелец теряет возможность изменять описание и заголовок, администраторы же этого права не теряют. После создания повязки изменить ее изображение невозможно.

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

DELETE /workshop/<external_id>

Strict Auth required
Удаляет повязку. Пользователь должен быть владельцем повязки или администратором.