Частичный объект по HTTP GET

Question

У нас есть коллекция документов:

class Document {
id;
title;
someContent;
creator;
...
}

Необходимо реализовать REST API, который в первом случае возвращает все документы со всеми полями («id», «title», «someContent» и т. Д.),Во втором случае верните все документы, но только часть полей (только «id» и «title»).

Каким способом лучше всего это сделать? Это хорошая идея, чтобы реализовать его в одной конечной точке с параметром запроса "поле"? Или лучше разделить их на разные конечные точки? Также я могу использовать для этого код статуса 206? Есть ли «наилучшая практика» для реализации этой функции?

Например, я могу сделать это так (но я не уверен, что это правильно):

GET /documents (200 status code)
GET /documents?field=id&filed=title (206 status code)

Следовательно,«field» - необязательный параметр запроса, который просто указывает поля, которые мы должны вернуть.

В первом Get все поля будут возвращены. Как пример: [{id: "5F1AB3", title: "Document 1", creatur: "John", ...}, {...}]. Во втором JSON только с двумя полями: ID и заголовок. Ответ выглядит следующим образом: [{id: "5F1AB3", title: "Document 1"}, {...}].

Answer 1

Эта статья описывает эту проблему: https://dev.to/andersonjoseph/what-they-want-is-what-they-get-the-partial-response-strategy-5a0m

Answer 2

Каким способом лучше всего это сделать?

Возможно, вам нужны два разных ресурса, во многом так же, как полноразмерное изображение и миниатюра - это разные ресурсы.

Если это разные ресурсы, то мы должны ожидатьсм. два разных идентификатора.

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

GET /documents
GET /documents?field=id&field=title

Эти идентификаторы в порядке. REST очень мало заботится о соглашениях по правописанию, которые вы используете для различения одного идентификатора от другого. Обратите внимание, что запрос является частью идентификатора - что касается компонентов общего назначения, это два разных идентификатора, эти два ресурса могут вообще не быть связаны друг с другом!

206 ЧастичноСодержание не очень хорошая идея;семантика 206 связана с Range Requests , что не очень подходит для того, что вы делаете.