Параметры URL-запроса или параметры типа носителя (в заголовке Accept), чтобы настроить ответ на HTTP-запрос?

Я работаю над созданием REST API, который может отвечать множеством форматов, один из которых представляет собой текстовый формат, который можно настроить для отображения или скрытия определенных аспектов из ответа (например, заголовки разделов или сносок). Традиционный способ, которым это делается, - это параметры URL-запроса, как для указания желаемого типа ответа, так и для параметров конфигурации, например:

http://api.example.com/foo-book/ch1/?format=text&headings=false&footnotes=true

Однако более элегантный способ RESTful указать желаемый тип ответа (вместо параметра запроса URL format=text) заключается в использовании заголовка Accept, например:

Accept: text/plain; charset=utf-8

Теперь, помимо URL-адресов, типы носителей могут принимать параметры за RFC 2046 и, как видно в вездесущем text/html; charset=utf-8 и в Accept заголовки типа audio/*; q=0.2. Он также показал, что созданные MIME-типы, созданные производителем, могут определять свои собственные параметры, такие как:

application/vnd.example-com.foo+json; version=1.0
application/vnd.example-info.bar+xml; version=2.0

Итак, для ранее зарегистрированных MIME-типов, таких как text/html или application/json, допустимо ли включать настраиваемые параметры для приложения? Например:

Accept: text/plain; charset=utf-8; headings=false; footnotes=true

Это похоже на элегантное решение RESTful, но похоже, что оно что-то нарушает. RFC 2046 §1 говорит:

Parameters are modifiers of the media subtype, and as such do not
fundamentally affect the nature of the content.  The set of
meaningful parameters depends on the media type and subtype.  Most
parameters are associated with a single specific subtype.  However, a
given top-level media type may define parameters which are applicable
to any subtype of that type.  Parameters may be required by their
defining media type or subtype or they may be optional.  MIME
implementations must also ignore any parameters whose names they do
not recognize.

Обратите внимание на это последнее предложение:

MIME implementations must also ignore any parameters whose names they do not recognize.

Означает ли это, что клиент был бы несоответствующим, если бы распознал параметр footnotes=true типа носителя text/plain?

Ответ 1

Мне кажется, что различие должно выполняться следующим образом:

Принять параметры заголовка относятся к упаковке ответа.

Тип носителя (например, application/json)
Кодировка символов (например, charset=utf-8)
Структура (например, расширения поставщика, которые определяют "doctype"; application/vnd.example-com.foo+json; version=1.0)

Параметры запроса относятся к ресурсам (адресам), адресованным.

Компоненты (например, заголовки и сноски)
Дополнительные функции (например, форматирование)
Ограничения (особенно при обращении к ряду похожих ресурсов)

Ответ 2

Давид Эйк прав.

Если вы меняете возвращаемое Entity, оно должно быть в URI. Все остальное будет разбивать всевозможные вещи, такие как кеширование и т.д.

"Формат" внутри URI, однако, в основном неправильный. Если вы можете, используйте Accept. Заголовки ответов уже установлены для обеспечения плавной езды.

Однако, если вы не можете использовать Accept (например, в стандартном веб-браузере), я рекомендую использовать расширение DOS или аналогично переопределять Accept.

e.g.
/image (is the resource)
/image.jpg
/image.gif