api - URL 查询参数或媒体类型参数(在 Accept header 中)来配置对 HTTP 请求的响应？

Question

我正在设计一个可以响应多种格式的 REST API，其中一种是纯文本格式，可以配置为显示或隐藏响应的某些方面(例如章节标题或脚注)。完成此操作的传统方法是通过 URL 查询参数，以指示所需的响应类型和配置选项，例如:

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

然而，一种更优雅的 RESTful 方式来指示所需的响应类型(而不是 format=text URL 查询参数)是使用 Accept header ，例如:

Accept: text/plain; charset=utf-8

现在，除了 URL 之外，媒体类型还可以根据 RFC 2046 采用参数正如无处不在的 text/html; charset=utf-8 和 Accept header ，例如 audio/*; q=0.2。也是shown供应商制作的 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.

这是否意味着如果客户端识别出 text/plain 媒体类型的 footnotes=true 参数，则客户端将不符合规范？

Answer 1

在我看来，区别应该如下:

接受 header 参数与响应的打包有关。

• 媒体类型(例如application/json)
• 字符编码(例如charset=utf-8)
• 结构(例如，指定“文档类型”的供应商扩展；application/vnd.example-com.foo+json；版本=1.0)

查询参数与寻址的资源有关。

• 组件(例如标题和脚注)
• 可选功能(例如格式化)
• 约束条件(尤其是在处理一系列类似资源时)