Question

I’m working on designing a REST API that can respond with a variety of formats, one of which is a plain text format which can be configured to show or hide certain aspects from the response (e.g. section headings or footnotes). The traditional way that this is done is via URL query parameters, both to indicate the desired response type and the configuration options, for example:

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

However, a more elegant RESTful way to indicate the desired response type (instead of the format=text URL query param) is to use the Accept header, for example:

Accept: text/plain; charset=utf-8

Now, in addition to URLs, media types can take parameters per RFC 2046 and as seen in the ubiquitous text/html; charset=utf-8 and in Accept headers like audio/*; q=0.2. It’s also shown that vendor-crafted MIME types can define their own parameters like:

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

So for previously-registered MIME types like text/html or application/json, is it acceptable to include custom parameters for an application’s needs? For example:

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

This seems like an elegant RESTful solution, but it also seems like it would be violating something. RFC 2046 §1 says:

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.

Note this last sentence:

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

Does this mean that a client would be non-conforming if they recognized a footnotes=true parameter of the text/plain media type?

Answer 1

It seems to me that the distinction should run as follows:

Accept header parameters pertain to the packaging of the response.

• Media type (e.g. application/json)
• Character encoding (e.g. charset=utf-8)
• Structure (e.g. vendor extensions that specify the “doctype”;
  application/vnd.example-com.foo+json; version=1.0)

Query parameters pertain to resource(s) as addressed.

• Components (e.g. headings and footnotes)
• Optional features (e.g. formatting)
• Constraints (especially when addressing a range of like resources)