Методы работы с тегами

На этой странице представлены основные методы API для работы с тегами категорий файлов в системе Brainysoft: создание, получение, обновление, удаление тегов, изменение порядка, публикация и снятие публикации, а также получение статистики по тегам.

Методы API работы с тегами категорий файлов

Метод	URL	Описание
GET|HEAD	api/tags	Получение списка тегов
POST	api/tags	Создание нового тега
PUT|PATCH	api/tags/{tag}	Обновление тега (title)
GET|HEAD	api/tags/{tag}	Получение информации о теге
DELETE	api/tags/{tag}	Удаление тега
PUT	api/tags/{tag}/changeOrder	Изменение порядка тегов
PUT	api/tags/{tag}/publish	Публикация тега
PUT	api/tags/{tag}/unpublish	Снятие публикации тега
GET	api/statistics/tags	Получить статистику по тегам

---

Получение списка тегов

GET /api/tags

Описание

Метод возвращает список всех доступных тегов категорий файлов с их атрибутами: название, алиас, статус, иерархия.

Пример запроса

GET /api/tags

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750164920000,         // Время ответа (UNIX timestamp, ms)
    "data": [
        {
            "id": 1,                   // Уникальный идентификатор тега
            "title": "Фотографии",     // Название тега (отображается пользователю)
            "alias": "fotografii",     // Техническое имя тега (может использоваться в URL/API)
            "status": "PUBLISHED",     // Статус тега
            "parentId": 0,             // ID родительского тега (0 — если тег верхнего уровня)
            "level": 1                 // Уровень вложенности (например, 1 — корневой тег)
        }
    ]
}

---

Создание нового тега

POST /api/tags

Описание

Метод позволяет создать новый тег в системе. В теле запроса передаются параметры нового тега, такие как название, алиас, статус, родительский тег и уровень вложенности.

Пример запроса

POST /api/tags

{
    "id": 46,                          // Уникальный идентификатор тега
    "title": "Документы для займа",    // Название тега (отображается пользователю)
    "alias": "loan_documents",         // Техническое имя тега (может использоваться в URL/API)
    "status": "PUBLISHED",             // Статус тега
    "parentId": 0,                     // ID родительского тега (0 — если тег верхнего уровня)
    "level": 1                         // Уровень вложенности (например, 1 — корневой тег)
}

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750682383000,         // Время ответа (UNIX timestamp, ms)
    "data": {
        "result": "ok",                // Результат операции
        "tag": 46                      // Уникальный идентификатор созданного тега
    }
}

---

Обновление тега (title)

PUT|PATCH /api/tags/{tag}

Описание

Метод позволяет изменить только название (title) существующего тега по его идентификатору. Другие поля (alias, status, parentId, level) изменить этим методом нельзя — они остаются без изменений, alias на основе нового title будет сгенерирован системой автоматически.

Параметры запроса

{tag} (integer, обязательный) — уникальный идентификатор тега.

Пример запроса

PUT|PATCH /api/tags/47

{
    "title": "Четвертый документ для займа"  // Новое название тега
}

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750683228000,         // Время ответа (UNIX timestamp, ms)
    "data": {
        "id": 47,                      // Уникальный идентификатор тега
        "title": "Четвертый документ для займа", // Название тега (отображается пользователю)
        "alias": "chetvertyiy-dokument-dlya-zayma", // Техническое имя тега (сгенерировано автоматически)
        "status": "PUBLISHED",         // Статус тега
        "parentId": null,              // ID родительского тега (null — если тег верхнего уровня)
        "level": 0                     // Уровень вложенности
    }
}

---

Получение информации о теге

GET /api/tags/{tag}

Описание

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

Параметры запроса

{tag} (integer, обязательный) — уникальный идентификатор тега.

Пример запроса

GET /api/tags/4

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750681352000,         // Время ответа (UNIX timestamp, ms)
    "data": {
        "id": 4,                       // Уникальный идентификатор тега
        "title": "Документы заемщика", // Название тега (отображается пользователю)
        "alias": "dokumentyi-zaemschika", // Техническое имя тега (может использоваться в URL/API)
        "status": "PUBLISHED",         // Статус тега
        "parentId": 0,                 // ID родительского тега (0 — если тег верхнего уровня)
        "level": 1                     // Уровень вложенности (например, 1 — корневой тег)
    }
}

---

Удаление тега

DELETE /api/tags/{tag}

Описание

Метод позволяет удалить тег по его идентификатору.

Параметры запроса

{tag} (integer, обязательный) — уникальный идентификатор тега.

Пример запроса

DELETE /api/tags/48

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750683985000,         // Время ответа (UNIX timestamp, ms)
    "data": {
        "status": "deleted"            // Статус удаления тега
    }
}

---

Изменение порядка тегов

PUT /api/tags/{tag}/changeOrder

Описание

Метод позволяет изменить порядок (позицию) тега относительно другого тега в списке. Для этого указывается идентификатор соседнего тега и желаемая позиция относительно него.

Параметры запроса

{tag} (integer, обязательный) — уникальный идентификатор тега, порядок которого изменяется.

Тело запроса (application/json)

Поле	Тип	Описание
neighborTagId	integer	Идентификатор соседнего тега, относительно которого будет изменён порядок
position	string	Позиция относительно соседнего тега. Возможные значения: "before" — перед указанным тегом, "after" — после указанного тега

Пример запроса

PUT /api/tags/47/changeOrder

{
    "neighborTagId": 46,               // Идентификатор соседнего тега
    "position": "after"                // Позиция относительно соседнего тега
}

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750833694000,         // Время ответа (UNIX timestamp, ms)
    "data": {
        "result": "ok",                // Результат операции
        "tag": 47,                     // Уникальный идентификатор тега
        "currentOrder": "0 46"         // Текущий порядок тегов
    }
}

---

Публикация и снятие публикации тега

PUT /api/tags/{tag}/publish - Публикация тега

PUT /api/tags/{tag}/unpublish - Снятие публикации тега

Описание

publish - метод переводит тег в статус "опубликован", делая его доступным для использования в системе.

unpublish - метод переводит тег в статус "не опубликован", делая его недоступным для использования в системе.

Параметры запроса

{tag} (integer, обязательный) — уникальный идентификатор тега.

Пример запроса

PUT /api/tags/47/unpublish

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750684897000,         // Время ответа (UNIX timestamp, ms)
    "data": {
        "id": 47,                      // Уникальный идентификатор тега
        "title": "Четвертый документ для займа", // Название тега (отображается пользователю)
        "alias": "chetvertyiy-dokument-dlya-zayma", // Техническое имя тега (может использоваться в URL/API)
        "status": "UNPUBLISHED",       // Статус тега
        "parentId": null,              // ID родительского тега (null — если тег верхнего уровня)
        "level": 0                     // Уровень вложенности
    }
}

---

Получить статистику по тегам

GET /api/statistics/tags

Описание

Метод возвращает статистику по всем тегам категорий файлов, включая количество файлов с каждым тегом.

Пример запроса

GET /api/statistics/tags

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750164401000,         // Время ответа (UNIX timestamp, ms)
    "data": {
        "tags": [
            {
                "id": 1,               // Уникальный идентификатор тега
                "alias": "fotografii", // Техническое имя тега (может использоваться в URL/API)
                "label": "Фотографии", // Название тега (синоним поля title, используется в статистике)
                "files": 0,            // Количество текущих файлов с этим тегом
                "deleted": 0,          // Количество удалённых файлов с этим тегом
                "all": 0               // Общее количество файлов с этим тегом
            }
        ]
    }
}

---

Описание полей

Поле	Тип	Описание
status	string	Статус выполнения запроса
timestamp	integer	Время ответа (UNIX timestamp, ms)
data	object/array	Основные данные ответа
id	integer	Уникальный идентификатор тега
title	string	Название тега (отображается пользователю)
alias	string	Техническое имя тега (может использоваться в URL/API)
status	string	Статус тега (PUBLISHED, UNPUBLISHED, DRAFT и др.)
parentId	integer	ID родительского тега (0 или null — если тег верхнего уровня)
level	integer	Уровень вложенности (например, 1 — корневой тег)
label	string	Название тега (синоним поля title, используется в статистике)
files	integer	Количество текущих файлов с этим тегом
deleted	integer	Количество удалённых файлов с этим тегом
all	integer	Общее количество файлов с этим тегом
result	string	Результат операции
tag	integer	Уникальный идентификатор тега
currentOrder	string	Текущий порядок тегов
neighborTagId	integer	Идентификатор соседнего тега
position	string	Позиция относительно соседнего тега