API docs by Redocly

Треугольники (3.0.0)

Описание

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

Данные

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

Приложение записывает все данные из оперативной памяти в CSV-файлы при завершении работы приложения.

Во время работы приложения ему запрещено взаимодействовать с файловой системой в другие моменты времени.

Список шаблонов треугольника

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

Id,SideA,SideB,SideC
4ae25b32-d794-4560-8a08-5e6d09a19c33,1,2,5
22f9f6c1-82af-4681-b92e-a3510ecee4b5,2,3,5
0c96ea19-fa65-499a-80ad-ea0c86b2a5e0,2,3,4

Список треугольников

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

Id,Template,RegistrationDateTime,BorderColor,FillColor,Description,Owner
66ade672-2301-4408-9471-8a17aa883d65,4ae25b32-d794-4560-8a08-5e6d09a19c33,2024-08-26T19:01:41.114511727,GREEN,RED,"странные данные, это неправильный треугольник",de42a00f-7f43-4d10-808d-bee47fdeef49
a6be5e23-b8d4-4d78-8aa3-1c204d0befc8,22f9f6c1-82af-4681-b92e-a3510ecee4b5,2024-07-10T17:26:41.129567382,RED,GREEN,"точки расположены на отрезке",de42a00f-7f43-4d10-808d-bee47fdeef49
baa30333-23d6-4eba-a8ed-7c235adf4228,0c96ea19-fa65-499a-80ad-ea0c86b2a5e0,2024-07-27T00:10:41.129642513,RED,GREEN,"обычный треугольник",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, обязательные параметры:

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

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

  Error: missing option --triangles-file

  Error: file not found «abc.csv»

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

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

jwt

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

  • sub – идентификатор пользователя, которому выдан токен (соответствует User→Id);
  • email – электронная почта пользователя, которому выдан токен (соответствует User→Email);
  • 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
Template
required
string <UUID>

Шаблон треугольника (соответствует Template→Id)

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

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

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

Цвет границы из списка цветов

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

Цвет заливки из списка цветов

Description
required
string

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

Responses

Request samples

Content type
application/json
{
  • "Template": "4ae25b32-d794-4560-8a08-5e6d09a19c33",
  • "RegistrationDateTime": "2024-01-01T00:00:00",
  • "BorderColor": "BLACK",
  • "FillColor": "BLACK",
  • "Description": "обыкновенный треугольник"
}

Response samples

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

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

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

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

идентификатор треугольника

Responses

Response samples

Content type
application/json
{
  • "Id": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Template": "4ae25b32-d794-4560-8a08-5e6d09a19c33",
  • "SideA": 3,
  • "SideB": 4,
  • "SideC": 5,
  • "RegistrationDateTime": "2024-01-01T00:00:00",
  • "BorderColor": "BLACK",
  • "FillColor": "BLACK",
  • "Description": "обыкновенный треугольник",
  • "Area": 6,
  • "Type": "Остроугольный",
  • "Owner": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "OwnerLogin": "User123"
}

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

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

идентификатор треугольника

Responses

Response samples

Content type
application/json
{
  • "Error": "Некорректный идентификатор треугольника. Для параметра triangle-id ожидается UUID, но получено значение «id»"
}

Получение списка треугольников, отфильтрованного по цвету границы

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

query Parameters
border-color
required
string
Enum: "BLACK" "WHITE" "RED" "GREEN" "BLUE" "YELLOW" "CYAN" "MAGENTA" "SILVER" "GRAY" "MAROON" "OLIVE" "DARKGREEN" "PURPLE" "TEAL"
Example: border-color=BLACK

Цвет границы треугольника

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
[
  • {
    }
]

Получение списка треугольников, отфильтрованного по площади

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

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

query Parameters
area-min
number <double>
Example: area-min=0.0

нижняя граница площади (включительно)

area-max
number <double>
Example: area-max=6.0

верхняя граница площади (включительно)

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
[
  • {
    }
]

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

В выдаче присутствуют только те цвета и типы треугольника, которые есть в списке данных.

Списки упорядочены лексикографически по возрастанию значения поля Color или Type соответственно.

query Parameters
by
required
any
Enum: "color" "type" "color,type"
Example: by=color,type

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

  • color – статистика по цвету заливки
  • type – статистика по типу треугольника
  • color,type – статистика по цвету заливки и по типу треугольника

Responses

Response samples

Content type
application/json
Example
[ ]

Создание нового треугольника по шаблону

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

Дата и время регистрации в системе устанавливаются автоматически по текущей дате и времени, если не переданы.

Владелец устанавливается по пользователю, выполнившему запрос.

Authorizations:
jwt
path Parameters
template-id
required
string <UUID>
Example: 4ae25b32-d794-4560-8a08-5e6d09a19c33

идентификатор шаблона

Request Body schema: application/json
required
RegistrationDateTime
string <date-time>
Default: "текущая дата и время"

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

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

Цвет границы из списка цветов

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

Цвет заливки из списка цветов

Description
required
string

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

Responses

Request samples

Content type
application/json
{
  • "RegistrationDateTime": "2024-01-01T00:00:00",
  • "BorderColor": "BLACK",
  • "FillColor": "BLACK",
  • "Description": "обыкновенный треугольник"
}

Response samples

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

Шаблоны

Методы, связанные с получением информации о шаблонах треугольников

Получение списка всех шаблонов

Список упорядочен по возрастанию идентификатора шаблона

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Создание нового шаблона

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

Authorizations:
jwt
Request Body schema: application/json
required
SideA
required
integer >= 1

Длина первой стороны (натуральное число)

SideB
required
integer >= 1

Длина второй стороны (натуральное число)

SideC
required
integer >= 1

Длина третьей стороны (натуральное число)

Responses

Request samples

Content type
application/json
{
  • "SideA": 3,
  • "SideB": 4,
  • "SideC": 5
}

Response samples

Content type
application/json
{
  • "Id": "4ae25b32-d794-4560-8a08-5e6d09a19c33"
}

Получение информации о шаблоне

Authorizations:
jwt
path Parameters
template-id
required
string <UUID>
Example: 4ae25b32-d794-4560-8a08-5e6d09a19c33

идентификатор шаблона

Responses

Response samples

Content type
application/json
{
  • "Id": "4ae25b32-d794-4560-8a08-5e6d09a19c33",
  • "SideA": 3,
  • "SideB": 4,
  • "SideC": 5,
  • "Area": 6,
  • "Type": "Остроугольный"
}

Редактирование шаблона

Authorizations:
jwt
Request Body schema: application/json
required

Список редактируемых полей.

SideA
required
integer >= 1

Длина первой стороны (натуральное число)

SideB
required
integer >= 1

Длина второй стороны (натуральное число)

SideC
required
integer >= 1

Длина третьей стороны (натуральное число)

Responses

Request samples

Content type
application/json
{
  • "SideA": 3,
  • "SideB": 4,
  • "SideC": 5
}

Response samples

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

Создание нового треугольника по шаблону

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

Дата и время регистрации в системе устанавливаются автоматически по текущей дате и времени, если не переданы.

Владелец устанавливается по пользователю, выполнившему запрос.

Authorizations:
jwt
path Parameters
template-id
required
string <UUID>
Example: 4ae25b32-d794-4560-8a08-5e6d09a19c33

идентификатор шаблона

Request Body schema: application/json
required
RegistrationDateTime
string <date-time>
Default: "текущая дата и время"

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

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

Цвет границы из списка цветов

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

Цвет заливки из списка цветов

Description
required
string

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

Responses

Request samples

Content type
application/json
{
  • "RegistrationDateTime": "2024-01-01T00:00:00",
  • "BorderColor": "BLACK",
  • "FillColor": "BLACK",
  • "Description": "обыкновенный треугольник"
}

Response samples

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

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

Методы, связанные с получением информации о пользователях

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

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

Authorizations:
jwt

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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

Дата и время регистрации в системе устанавливаются автоматически по текущей дате и времени.

Идентификатор и имя пользователя используются из JWT-токена.

Authorizations:
jwt
Request Body schema: application/x-www-form-urlencoded
required
Login
required
string

Уникальное имя пользователя. Не может быть пустым

Responses

Request samples

Content type
application/x-www-form-urlencoded
Login=%D0%9D%D0%BE%D0%B2%D1%8B%D0%B9%20%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8C

Response samples

Content type
application/json
{
  • "Login": {
    }
}

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

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

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

query Parameters
user-role
required
string (Роль пользователя)
Enum: "User" "TemplateManager" "UserManager"
Example: user-role=User

роль пользователя

Responses

Response samples

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

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

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

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

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

Responses

Response samples

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

Шаблон треугольника

Id
string <UUID>

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

SideA
integer >= 1

Длина первой стороны (натуральное число)

SideB
integer >= 1

Длина второй стороны (натуральное число)

SideC
integer >= 1

Длина третьей стороны (натуральное число)

Area
number or null (Площадь треугольника)

Вычисляемое поле, отсутствует в файле с данными.
Площадь отрезка = 0. Площадь некорректного треугольника = null

Type
string (Тип треугольника)
Enum: "Некорректный" "Отрезок" "Остроугольный" "Прямоугольный" "Тупоугольный"

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

  • Некорректный (наибольшая сторона больше суммы двух других)
  • Отрезок (наибольшая сторона равна сумме двух других)
  • Остроугольный (квадрат наибольшей стороны меньше суммы квадратов двух других)
  • Прямоугольный (квадрат наибольшей стороны равен сумме квадратов двух других)
  • Тупоугольный (квадрат наибольшей стороны больше суммы квадратов двух других)
{
  • "Id": "4ae25b32-d794-4560-8a08-5e6d09a19c33",
  • "SideA": 3,
  • "SideB": 4,
  • "SideC": 5,
  • "Area": 6,
  • "Type": "Остроугольный"
}

Треугольник

Id
string <UUID>

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

Template
string <UUID>

Шаблон треугольника (соответствует Template→Id)

RegistrationDateTime
string <date-time>

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

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

Цвет границы из списка цветов

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

Цвет заливки из списка цветов

Description
string

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

Owner
string <UUID>

Владелец треугольника (соответствует User→Id)

{
  • "Id": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Template": "4ae25b32-d794-4560-8a08-5e6d09a19c33",
  • "RegistrationDateTime": "2024-01-01T00:00:00",
  • "BorderColor": "BLACK",
  • "FillColor": "BLACK",
  • "Description": "обыкновенный треугольник",
  • "Owner": "de42a00f-7f43-4d10-808d-bee47fdeef49"
}

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

Id
string <UUID>

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

Login
string

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

RegistrationDateTime
string <date-time>

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

Email
string

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

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

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

Роль Доступно
User Зарегистрированный пользователь
TemplateManager Менеджер шаблонов треугольников
UserManager Менеджер пользователей приложения
{
  • "Id": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Login": "User123",
  • "RegistrationDateTime": "2024-01-01T00:00:00",
  • "Email": "user123@crafted.su",
  • "Role": "User"
}