Ответ в REST API?

Question

[spirt_etilovy]

Сейчас занимаюсь проектированием API. Не могу решить в каком формате лучше возвращать данные.
Практически во всех API, которые я рассматривал, результаты хранят в отдельном поле объекта. Например:

{
    "data": "some data (object|array|etc)"
}

Вопрос: нужно ли оборачивать результаты так, как указано выше и зачем это делается?
Ведь можно же просто передавать в ответе данные, а всю дополнительную информацию передавать в заголовках (статус (200, 404....), пагинация и т.д).

Comments

[yurygolikov]

Обертка это вы про JSON формат?

[spirt_etilovy]

yurygolikov: ага

[yurygolikov]

spirt_etilovy: Можно и в заголовках, но тк обычно инфы кроме data бывает много, то более принято все таки чтобы data была в дате :) А что вас смущает?

Answer 1

[RidgeA]

Зависит от потребностей.
Пагинация через заголовки ИМХО решение так себе.
Для вдохновения можно посмотреть как сделано jsonapi.org или www.odata.org

Answer 2

[Станислав Макаров]

HAL, Siren, JSON-LD (последний похардкорнее, не факт что вам подойдёт).

Answer 3

[⚡ Kotobotov ⚡]

привет брат поразуму, всегда также делаю и считаю глупостей вначале передавать код 200 (все оке), а потом еще в ответе писать {статус: "все оке"}

с другой стороны полно недалеких разрабов, которые не знают как работать с заголовками - и если у тебя какой-то массовый сервис для дебилов, то возможно им нужно дублировать и в теле инфомацию, но я не понимаю как ты для них продублируешь инфу в ответе если например сервак упал, или там 404 выдал.
хотя я за чистоту апи, чтоб служебной информации в ответе не было, вся служебная информация чтоб в заголовках ппередавалась.
С другой стороны АПИ должно быть понятным и очевидным без документации, поэтому лучше передавать не просто массив, а именнованный данные.
Пример:
запрос гет хттп://юзер/1
ответ {имя: "вася", возраст: 18}, а не {["вася", "18"]}