Правильный способ ответить на оставшийся постраничный запрос

Question

Я хочу создать REST-совместимую конечную точку в Spring. Предполагается, что конечная точка допускает разбиение на страницы.

Запрос довольно прост, GET to url / resource? Page = 1 & pageSize = 20. Проблема заключается в запросе.

Я нашел 2 больших способа возврата данных:

1. Возвращает пользовательский объект, содержащий:

{
    "page": 1,
    "pageSize": 20,
    "content": [
         {...},
         {...}
         ...
    ]
}

Проблема этого метода в том, что он больше не возвращает ресурс, а возвращает оболочку для ресурса.

Установить пользовательский заголовок X-Total-Count, когда вы даете ответ от бэкэнда:

[
   {...},
   {...}
   ...
]

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

Я хотел бы знать, какие стандарты более широко используются и почему? Что такое «новый» подход к этому? От чего мне держаться подальше? Есть ли способ удовлетворить обе потребности?

Заранее спасибо!

Answer 1

Наиболее распространенная практика, которую я вижу в API, который я использую, это ваш первый пример с обёрткой объекта:

{
    "page": 1,
    "pageSize": 20,
    "content": [
         {...},
         {...}
         ...
    ]
}

Обычно эта обёртка объекта реализуется с любым вызовом конечной точки GET /resources. С другой стороны, когда пользователи вызывают конечную точку GET resource/{resourceId}, обертка объекта отсутствует.

Это мое мнение относительно того, что я вижу в использовании других API, но я написал около 100 различных интеграций API, поэтомуЯ видел изрядную сумму.