Имеет ли смысл использовать параметры запроса и тела в запросе POST для REST API?

Question

У меня есть ресурс, который по существу требует другого ресурса в качестве входных данных для создания. Например:

POST /v1/NewResource 
body: {InputResource} 

Самое интересное, однако, заключается в том, что создание NewResource дорого, а сам ресурс является временным (не сохранилась). Некоторым потребителям может потребоваться только часть ресурса. Итак, у меня действительно есть два входных параметра: данные, необходимые для создания, а затем обработка инструкций от потребителя, чтобы контролировать, как много работы действительно делается.

Я вижу два пути (по крайней мере):

POST /v1/NewResource?detailLevel=base|full 
body: {InputResource} 

против

POST /v1/NewResource 
body: {Request.detailLevel and Request.InputResource} 

Является первым один даже вариант? У кого-нибудь есть какие-либо предпочтения/опыт в любом случае? Существует определенная элегантность в том, что полезная нагрузка - это только данные, необходимые и отделяющие от инструкций по обработке. Я понимаю, что здесь нет правильного или неправильного ответа, просто любопытно в мыслях сообщества.

Answer 1

Смешивание запросов и содержимого URI выглядит как действительный HTTP, поскольку спецификация не заявляет, что они являются взаимоисключающими в приложении http-сервера, которое принимает запросы POST.

RFC 3986 определяет строки http-запросов как часть uri, которая работает как неиерархический способ нахождения ресурса. Однако архитектура RESTful обычно не предусматривает схемы URI для работы очень определенным образом, вместо этого фокусируется больше на удовлетворении таких свойств, как кешируемость, дизайн ресурсов и идемпотентность, и меньше на то, как ресурсы расположены.

Я бы предпочел пойти первым путем, поскольку detailLevel не является частью самого ресурса.

Answer 2

На самом деле нет правильного или неправильного решения в отношении дизайна REST и URI. На самом деле это сводится к личным предпочтениям. Семантика полезной нагрузки POST полностью зависит от сервера. Это означает, что полностью зависит от вас, как частичные или полные данные должны отличаться друг от друга и/или обрабатываться сервером.

поэтому у вас есть несколько маршрутов вы могли бы пойти:

• держать флаг Wheter полезной нагрузки тела представляет собой полную или частичную информацию в теле
• Отправить информацию о полной или частичной информации через URI
• Поскольку информация о содержимом может рассматриваться как метаданные, описывающие тело, вы можете ввести новый HTTP-заголовок, который помещает содержимое как полное или частичное.
• Создайте собственные типы контента для каждого типа полезной нагрузки

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

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