Сервис предоставляет возможность манипулировать объектами виджетов
Сервис спроектирован в соответсвии с REST-архитектурным стилем. Для отражения принципа Uniform Interface и HATEOAS был выбран формат HAL, однако для сохранения совместимости формат ответов остался json.
Для оценки корректности работы с http-протоколом была выбрана RMM-модель (Richardson Maturity Model), по которой сервис соответсвует RMM-сервису 3-его уровня.
GET /api/widgets?
[page=<номер страницы ответа>]
[size=<количество виджетов на каждой странице ответа>]
[bottomLeftX=<x-координата левой нижней точки прямоугольной области фильтрации>]
[bottomLeftY=<y-координата левой нижней точки прямоугольной области фильтрации>]
[upperRightX=<x-координата правой верхней точки прямоугольной области фильтрации>]
[upperRightY=<y-координата правой верхней точки прямоугольной области фильтрации>]
Параметры:
-
page- Номер страницы ответа. Типint. Значение по умолчанию — 1. Опциональный параметр -
size- Количество виджетов на каждой странице ответа. Типint. Допустимые значения: от 1 до 500. Значение по умолчанию — 10. Опциональный параметр. -
bottomLeftX, bottomLeftY- Координаты левой нижней точки прямоугольной области фильтрации. Опциональные параметры, однако обязательны в случае указания параметров из пункта 4 -
upperRightX, upperRightY- Координаты правой верхней точки прямоугольной области фильтрации. Опциональные параметры, однако обязательны в случае указания параметров из пункта 3
curl -X GET 'http://localhost:8080/api/widgets?page=1&bottomLeftX=0&bottomLeftY=0&upperRightX=300&upperRightY=200'
"links": [
{
"rel": "self",
"href": "http://localhost:8080/api/widgets?page=1&size=10",
"type": "GET"
},
{
"rel": "create-widget",
"href": "http://localhost:8080/api/widgets",
"type": "POST"
}
],
"content": [
{
"xcoordinate": 60,
"ycoordinate": 60,
"zindex": 16,
"links": [
{
"rel": "self",
"href": "http://localhost:8080/api/widgets/723150e1-6b39-47cb-8277-04fca5f7d95f",
"type": "GET"
}
],
"id": "723150e1-6b39-47cb-8277-04fca5f7d95f",
"xСoordinate": 60,
"yСoordinate": 60,
"zIndex": 16,
"width": 110,
"height": 110,
"modifiedAt": "2019-11-29 05:24:47"
}
],
"page": {
"size": 1,
"totalElements": 9,
"totalPages": 1,
"number": 1
}
}
Структура ответа:
Массив - content доступные виджеты
Массив - links для поддержки формата HAL
| Название | Что означает |
|---|---|
link.rel |
Тип relation, ассоциированный с ресурсом |
link.href |
Ссылка на доступный ресурс из текущего состояния |
type |
Тип http-метода |
Типы relation
| Название | Что означает |
|---|---|
self |
Текущий ресурс |
prev |
Предыдущий доступный ресурс |
next |
Следующий доступный ресурс |
widget |
Запрашиваем виджет |
widgets |
Запрашиваем виджеты |
create |
Создаем виджет |
update |
Обновляем виджет |
remove |
Удаляем виджет |
Объект - page
| Название | Что означает |
|---|---|
page.size |
Количество элементов на странице |
page.totalElements |
Общее количество элементов |
page.totalPages |
Общее количество страниц |
page.number |
Номер страницы |
GET /api/widgets/[<uuid>]
Параметры:
uuid - Уникальный идентификатор виджета. Тип uuid. Обязательный параметр
curl -X GET http://localhost:8080/api/widgets/e098fab1-8fa5-4b87-b29d-2b3fa616d042
"id": "e098fab1-8fa5-4b87-b29d-2b3fa616d042",
"xСoordinate": 15,
"yСoordinate": 25,
"zIndex": 4,
"width": 100,
"height": 100,
"modifiedAt": "2019-11-25 07:25:40",
"links": [
{
"rel": "self",
"href": "http://localhost:8080/api/widgets/e098fab1-8fa5-4b87-b29d-2b3fa616d042",
"type": "GET"
},
{
"rel": "update",
"href": "http://localhost:8080/api/widgets/e098fab1-8fa5-4b87-b29d-2b3fa616d042",
"type": "PUT"
},
{
"rel": "remove",
"href": "http://localhost:8080/api/widgets/e098fab1-8fa5-4b87-b29d-2b3fa616d042",
"type": "DELETE"
},
{
"rel": "widgets",
"href": "http://localhost:8080/api/widgets",
"type": "GET"
}
]
}
Поля объекта widget
| Название | Что означает |
|---|---|
id |
Уникальный идентификатор виджета |
xСoordinate |
x-координата |
yСoordinate |
y-координата |
zIndex |
z-координата |
width |
ширина |
height |
высота |
modifiedAt |
Дата обновления в формате yyyy-MM-dd HH:mm:ss |
POST /api/widgets
Параметры:
{ "xcoordinate": 15, "ycoordinate": 25, "zIndex": 0, "width": 100, "height": 100 }.
-
xcoordinate- x-координата виджета. Типlong. Значение по умолчанию — 0. -
ycoordinate- y-координата виджета. Типlong. Значение по умолчанию — 0. -
zIndex- z-координата виджета. Типlong. Значение по умолчанию выставляется согласно тз. -
width- ширина виджета. Типlong. Значение по умолчанию - 1, диапазон значений от 1. -
height- высота виджета. Типlong. Значение по умолчанию - 1, диапазон значений от 1.
curl -X POST \
http://localhost:8080/api/widgets \
-H 'Content-Type: application/json' \
-d '{
"xcoordinate": 1115,
"ycoordinate": 25,
"zIndex": 8,
"width": 100,
"height": 100
}
В качестве успешного ответа приходит карточка созданного виджета
{
"timestamp": 1574650406828,
"status": 400,
"error": "Bad Request",
"messages": [
"Field `width` must be greater than 0"
]
}
PUT /api/widgets[<uuid>]
Параметры:
{
"xcoordinate": 15,
"ycoordinate": 25,
"zIndex": 0,
"width": 100,
"height": 100
}
-
xcoordinate- x-координата виджета. Типlong. Значение по умолчанию — 0. -
ycoordinate- y-координата виджета. Типlong. Значение по умолчанию — 0. -
zIndex- z-координата виджета. Типlong. Значение по умолчанию выставляется согласно тз. -
width- ширина виджета. Типlong. Значение по умолчанию - 1, диапазон значений от 1. -
height- высота виджета. Типlong. Значение по умолчанию - 1, диапазон значений от 1.
curl -X PUT \
http://localhost:8080/api/widgets/42fbdb99-f75b-43d8-9d17-d345255e8572 \
-H 'Content-Type: application/json' \
-d '{
"xcoordinate": 1115,
"ycoordinate": 25,
"zIndex": 9,
"width": 100,
"height": 100
}
В качестве успешного ответа приходит карточка созданного виджета
Аналогичен ошибочному ответу при создании виджета
DELETE /api/widgets[<uuid>]
curl -X DELETE \ http://localhost:8080/api/widgets/42fbdb99-f75b-43d8-9d17-d345255e8572
В качестве успешного ответа приходит карточка удаленного виджета
Аналогичен ошибочному ответу при создании и обновлении виджета