API docs by Redocly

Список задач (3.0.0)

Описание

Приложение, решающее задачу по управлению списком с данными.

Данные

Приложение считывает все данные из соответствующих CSV-файлов (разделитель – запятая) при старте приложения.

Список задач

Имя файла с исходными данными передаётся приложению с ключом --tasks-file

Id,Title,RegistrationDateTime,StartDateTime,EndDateTime,Importance,Urgency,Percentage,Description,Author,Category
8b2a4482-35c8-411e-aab9-6ce490b3bea1,Задача № 1,2024-01-01T00:00:00.0,2024-01-01T00:00:00.0,,Очень низкий,false,100,задача,de42a00f-7f43-4d10-808d-bee47fdeef49,10c50d8a-fc9e-45ba-b303-7a623f4c699b
ec247f48-f86c-45c8-ab2f-7510e4640052,Задача № 2,2024-01-02T00:00:00.0,2024-01-02T00:00:00.0,2024-01-06T00:00:00.0,Очень низкий,false,0,задача,de42a00f-7f43-4d10-808d-bee47fdeef49,10c50d8a-fc9e-45ba-b303-7a623f4c699b
b0d29fa9-cfd4-41e2-9753-f9b5f40e9811,Задача № 3,2024-01-03T00:00:00.0,2024-01-03T00:00:00.0,2024-01-04T00:00:00.0,Критический,true,90,задача,de42a00f-7f43-4d10-808d-bee47fdeef49,10c50d8a-fc9e-45ba-b303-7a623f4c699b
a89723c3-0bfe-41b1-b7b9-db67a8c4708a,Задача № 4,2024-01-04T00:00:00.0,2024-01-04T00:00:00.0,,Очень низкий,false,0,задача,de42a00f-7f43-4d10-808d-bee47fdeef49,10c50d8a-fc9e-45ba-b303-7a623f4c699b
5bdb77b9-3a66-4217-b6fe-2eaaf9e54200,Задача № 5,2024-01-05T00:00:00.0,2024-01-05T00:00:00.0,,Высокий,false,70,задача,de42a00f-7f43-4d10-808d-bee47fdeef49,10c50d8a-fc9e-45ba-b303-7a623f4c699b
2aeaf2b4-ad18-4686-a69c-9d9baa34fe69,Задача № 6,2024-01-06T00:00:00.0,2024-01-06T00:00:00.0,,Очень низкий,true,5,задача,de42a00f-7f43-4d10-808d-bee47fdeef49,10c50d8a-fc9e-45ba-b303-7a623f4c699b

Список категорий

Имя файла с исходными данными передаётся приложению с ключом --categories-file

Id,Description,Color,Owner
10c50d8a-fc9e-45ba-b303-7a623f4c699b,Учебные задачи,BLACK,de42a00f-7f43-4d10-808d-bee47fdeef49

Список пользователей

Имя файла с исходными данными передаётся приложению с ключом --users-file

Id,Login,RegistrationDateTime,Email,Role
de42a00f-7f43-4d10-808d-bee47fdeef49,User123,2024-01-01T00:00:00,user123@crafted.su,User

Запуск приложения

Приложение запускается с помощью системы сборки Gradle, обязательные параметры:

  • --tasks-file – имя файла с данными приложения
  • --categories-file – имя файла с данными приложения
  • --users-file – имя файла с пользователями приложения
  • --port – порт, по которому доступен веб-сервер
  • --secret - секретный ключ для HMAC512, который используется для подписи JWT-токенов.
./gradlew run --args="--tasks-file ../sample-data/tasks.csv --categories-file ../sample-data/categories.csv --users-file ../sample-data/users.csv --port 9000 --secret SECRET"

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

Error: missing option --users-file

Error: file not found «abc.csv»

Аутентификация

Во время выполнения запроса пользователь может передать JWT-токен в HTTP-заголовке Authorization в формате Bearier. Отправка Bearier-токена через HTTP-форму или параметры URI не будет выполняться.

jwt

Токен содержит следующие ключи:

  • sub – имя пользователя, которому выдан токен (соответствует User→Login);
  • exp – время, когда токен станет невалидным.
Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer
Bearer format: JWT

Для указанного пользователя определяется роль User→Role. В каждом запросе приведён список ролей, для которых допустимо выполнения запроса. Также присутствуют роли:

  • Owner – выполнение запроса разрешено владельцу объекта.

Все дополнительные роли и правила доступа приведены в описании маршрута.

Если в описании маршрута отсутствует блок Authorizations, маршрут доступен всем пользователям.

Если блок Authorizations присутствует, но список ролей пуст или all, маршрут доступен всем зарегистрированным пользователям вне зависимости от роли.

Базовые маршруты

Маршруты проверки работоспособности веб-сервера

Проверка, запущен ли веб-сервер

Маршрут обязательно должен быть реализован, при отсутствии приложение не будет проверяться.

Responses

Задачи

Методы, связанные с задачами

Получение списка всех задач

Список упорядочен по возрастанию даты и времени регистрации и id.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Номер страницы.

Если номер превышает максимально возможный, приложение возвращает пустой список.

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

records-per-page
integer
Default: 10
Enum: 5 10 20 50
Example: records-per-page=10

Количество записей на странице.

Если количество передано и не входит в указанный набор значений, приложение возвращает сообщение об ошибке.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Создание новой задачи

Отсутствие необязательных параметров подразумевает, что поля заполняются значениями по умолчанию.

Идентификатор задачи генерируется уникальным.

Автор задачи соответствует переданному.

Authorizations:
jwt
Request Body schema: application/json
required
Title
required
string

Название задачи (не может быть пустым)

RegistrationDateTime
string <date-time>
Default: "текущая дата и время"

Дата и время регистрации задачи в системе

StartDateTime
string <date-time>
Default: "RegistrationDateTime"

Дата и время начала задачи

EndDateTime
string or null <date-time>
Default: null

Дата и время планового окончания задачи

Importance
string
Default: "Обычный"
Enum: "Очень низкий" "Низкий" "Обычный" "Высокий" "Очень высокий" "Критический"

Приоритет задачи

Urgency
boolean
Default: false

Срочность задачи

Percentage
integer [ 0 .. 100 ]
Default: 0

Процент выполнения задачи

Description
string
Default: ""

Описание задачи

Category
required
string or null <UUID>

Категория задачи (соответствует Category→Id)

Responses

Request samples

Content type
application/json
{
  • "Title": "Лабоработная № 3",
  • "RegistrationDateTime": "2024-01-01T00:00:00",
  • "StartDateTime": "2024-10-01T00:00:00",
  • "EndDateTime": "2025-01-01T00:00:00",
  • "Importance": "Очень низкий",
  • "Urgency": true,
  • "Percentage": 90,
  • "Description": "реализовать приложение для лабораторной № 3",
  • "Category": "10c50d8a-fc9e-45ba-b303-7a623f4c699b"
}

Response samples

Content type
application/json
{
  • "Id": "de42a00f-7f43-4d10-808d-bee47fdeef49"
}

Получение информации о задаче

Получение полной информации о задаче по идентификатору задачи

Authorizations:
jwt
path Parameters
task-id
required
string <UUID>
Example: de42a00f-7f43-4d10-808d-bee47fdeef49

идентификатор задачи

Responses

Response samples

Content type
application/json
{
  • "Id": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Title": "Лабоработная № 3",
  • "RegistrationDateTime": "2024-01-01T00:00:00",
  • "StartDateTime": "2024-10-01T00:00:00",
  • "EndDateTime": "2025-01-01T00:00:00",
  • "Importance": "Очень низкий",
  • "Urgency": true,
  • "Percentage": 90,
  • "Description": "реализовать приложение для лабораторной № 3",
  • "IsClosed": false,
  • "Author": "a2c5117e-c202-4e94-a819-6a44e008b301",
  • "AuthorEmail": "user123@crafted.su",
  • "Category": "10c50d8a-fc9e-45ba-b303-7a623f4c699b",
  • "CategoryDescription": "Учебные задачи"
}

Редактирование задачи

Отсутствие необязательных параметров подразумевает, что поля не изменяются.

Authorizations:
jwt
path Parameters
task-id
required
string <UUID>
Example: de42a00f-7f43-4d10-808d-bee47fdeef49

идентификатор задачи

Request Body schema: application/json
required
Title
required
string

Название задачи (не может быть пустым)

RegistrationDateTime
string <date-time>

Дата и время регистрации задачи в системе

StartDateTime
string <date-time>

Дата и время начала задачи

EndDateTime
string or null <date-time>

Дата и время планового окончания задачи

Importance
string
Enum: "Очень низкий" "Низкий" "Обычный" "Высокий" "Очень высокий" "Критический"

Приоритет задачи

Urgency
boolean

Срочность задачи

Percentage
integer [ 0 .. 100 ]

Процент выполнения задачи

Description
string

Описание задачи

Category
required
string or null <UUID>

Категория задачи (соответствует Category→Id)

Responses

Request samples

Content type
application/json
{
  • "Title": "Лабоработная № 3",
  • "RegistrationDateTime": "2024-01-01T00:00:00",
  • "StartDateTime": "2024-10-01T00:00:00",
  • "EndDateTime": "2025-01-01T00:00:00",
  • "Importance": "Очень низкий",
  • "Urgency": true,
  • "Percentage": 90,
  • "Description": "реализовать приложение для лабораторной № 3",
  • "Category": "10c50d8a-fc9e-45ba-b303-7a623f4c699b"
}

Response samples

Content type
application/json
Example
{
  • "Value": "{",
  • "Error": "Missing a name for object member."
}

Получение списка задач для блока Матрицы Эйзенхауэра

Обязательно должен быть передан хотя бы один из параметров.

Список упорядочен по возрастанию даты и времени регистрации и id.

Только задачи пользователя, выполнившего запрос.

Authorizations:
jwt
query Parameters
important
boolean
Example: important=true

Важность задачи.

  • true – задачи с приоритетом:
    • Высокий
    • Очень высокий
    • Критический
  • false – задачи с приоритетом:
    • Очень низкий
    • Низкий
    • Обычный
urgent
boolean
Example: urgent=true

Срочность задачи

page
integer >= 1
Default: 1
Example: page=1

Номер страницы.

Если номер превышает максимально возможный, приложение возвращает пустой список.

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

records-per-page
integer
Default: 10
Enum: 5 10 20 50
Example: records-per-page=10

Количество записей на странице.

Если количество передано и не входит в указанный набор значений, приложение возвращает сообщение об ошибке.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Получение списка задач, актуальных на момент времени

Получение списка задач, для которых дата и время начала меньше переданных и процент выполнения меньше 100%.

Список упорядочен по убыванию приоритета (Importance), убыванию срочности (Urgency), возрастанию даты регистрации и id.

Только задачи пользователя, выполнившего запрос.

Authorizations:
jwt
query Parameters
time
required
string <date-time>
Example: time=2024-01-03T00:00:00.0

Дата и время в формате ISO

page
integer >= 1
Default: 1
Example: page=1

Номер страницы.

Если номер превышает максимально возможный, приложение возвращает пустой список.

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

records-per-page
integer
Default: 10
Enum: 5 10 20 50
Example: records-per-page=10

Количество записей на странице.

Если количество передано и не входит в указанный набор значений, приложение возвращает сообщение об ошибке.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Получение статистической информации

Получение статистической информации по дням недели переданного параметры даты.

Значение null сопоставляется дню недели Не заполнено.

Список упорядочен последовательно по дню недели, «Не заполнено» (при наличии) в конце. Дни недели, для которых нет данных, пропущены.

Учитываются только задачи пользователя, выполнившего запрос.

Authorizations:
jwt
query Parameters
by-date
required
string
Enum: "registration" "start" "end"
Example: by-date=registration

Тип запрашиваемой статистики.

  • registration – статистика по дате регистрации
  • start – статистика по дате начала задачи
  • end – статистика по дате окончания задачи

Responses

Response samples

Content type
application/json
Example
{
  • "StatisticsByRegistrationDateTime": {
    }
}

Категории

Методы, связанные с категориями задач

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

Список упорядочен по возрастанию описания категории и id

Authorizations:
jwt

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Редактирование категории

Authorizations:
jwt
path Parameters
category-id
required
string <UUID>
Example: 10c50d8a-fc9e-45ba-b303-7a623f4c699b

идентификатор категории

Request Body schema: application/x-www-form-urlencoded
required
Description
required
string

Описание категории

Color
string

Цвет задач категории для отметки в календаре.

Может быть передан как цветом (BLACK, WHITE...), так и значением RGB (#000000, #FFFFFF...)

Responses

Request samples

Content type
application/x-www-form-urlencoded
Description=%D0%A3%D1%87%D0%B5%D0%B1%D0%BD%D1%8B%D0%B5%20%D0%B7%D0%B0%D0%B4%D0%B0%D1%87%D0%B8&Color=%2300FF00

Response samples

Content type
application/json
Example
{
  • "Error": "Некорректное значение переданного параметра X. Ожидается UUID, но получено текстовое значение"
}

Удаление категории

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

Authorizations:
jwt
path Parameters
category-id
required
string <UUID>
Example: 10c50d8a-fc9e-45ba-b303-7a623f4c699b

идентификатор категории

Responses

Response samples

Content type
application/json
{
  • "Error": "Некорректное значение переданного параметра X. Ожидается UUID, но получено текстовое значение"
}

Пользователи

Методы, связанные с пользователями приложения

Получение списка всех пользователей приложения

Список упорядочен по возрастанию имени пользователя

Authorizations:
jwt

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Удаление пользователя

Authorizations:
jwt
path Parameters
user-id
required
string <UUID>
Example: a2c5117e-c202-4e94-a819-6a44e008b301

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

Responses

Response samples

Content type
application/json
{
  • "Error": "Некорректное значение переданного параметра X. Ожидается UUID, но получено текстовое значение"
}

Задача (Task)

Id
string <UUID>

Уникальный идентификатор задачи

Title
string

Название задачи (не может быть пустым)

RegistrationDateTime
string <date-time>

Дата и время регистрации задачи в системе

StartDateTime
string <date-time>

Дата и время начала задачи

EndDateTime
string or null <date-time>

Дата и время планового окончания задачи

Importance
string (Importance)
Enum: "Очень низкий" "Низкий" "Обычный" "Высокий" "Очень высокий" "Критический"

Приоритет задачи

Urgency
boolean

Срочность задачи

Percentage
integer [ 0 .. 100 ]

Процент выполнения задачи

Description
string

Описание задачи

IsClosed
boolean

Вычисляемое поле, отсутствует в файле с данными Закрыта ли задача?

  • true – задача закрыта (процент выполнения 100%)
  • false – задача ещё не закрыта (процент выполнения не 100%)
Author
string <UUID>

Автор/Создатель задачи (соответствует User→Id)

Category
string or null <UUID>

Категория задачи (соответствует Category→Id)

{
  • "Id": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Title": "Лабоработная № 3",
  • "RegistrationDateTime": "2024-01-01T00:00:00",
  • "StartDateTime": "2024-10-01T00:00:00",
  • "EndDateTime": "2025-01-01T00:00:00",
  • "Importance": "Очень низкий",
  • "Urgency": true,
  • "Percentage": 90,
  • "Description": "реализовать приложение для лабораторной № 3",
  • "IsClosed": false,
  • "Author": "a2c5117e-c202-4e94-a819-6a44e008b301",
  • "Category": "10c50d8a-fc9e-45ba-b303-7a623f4c699b"
}

Категория (Category)

Id
string <UUID>

Уникальный идентификатор категории

Description
string

Описание категории

Color
string
Enum: "BLACK" "WHITE" "RED" "GREEN" "BLUE" "YELLOW" "CYAN" "MAGENTA" "SILVER" "GRAY" "MAROON" "OLIVE" "DARKGREEN" "PURPLE" "TEAL"

Цвет задач категории для отметки в календаре. Возможные варианты:

Цвет Описание RGB
BLACK Чёрный #000000
WHITE Белый #FFFFFF
RED Красный #FF0000
GREEN Зелёный #00FF00
BLUE Синий #0000FF
YELLOW Желтый #FFFF00
CYAN Голубой #00FFFF
MAGENTA Пурпурный #FF00FF
SILVER Серебряный #C0C0C0
GRAY Серый #808080
MAROON Бордовый #800000
OLIVE Оливковый #808000
DARKGREEN Тёмно-зелёный #008000
PURPLE Фиолетовый #800080
TEAL Бирюзовый #008080
Owner
string or null <UUID>

Владелец (соответствует User→Id).

null – общая категория, доступная для всех пользователей.

{
  • "Id": "10c50d8a-fc9e-45ba-b303-7a623f4c699b",
  • "Description": "Учебные задачи",
  • "Color": "BLACK",
  • "Owner": "a2c5117e-c202-4e94-a819-6a44e008b301"
}

Пользователь (User)

Id
string <UUID>

Уникальный идентификатор пользователя

Login
string

Уникальное имя пользователя

RegistrationDateTime
string <date-time>

Дата и время регистрации в системе

Email
string

Электронная почта пользователя

Role
string (Роль пользователя)
Enum: "User" "CategoryManager" "UserManager"

Роль, в зависимости от которой определяются возможности пользователя.

Роль Доступно
User Зарегистрированный пользователь
CategoryManager Менеджер категорий
UserManager Менеджер пользователей приложения
{
  • "Id": "a2c5117e-c202-4e94-a819-6a44e008b301",
  • "Login": "User123",
  • "RegistrationDateTime": "2024-01-01T00:00:00",
  • "Email": "user123@crafted.su",
  • "Role": "User"
}