StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

POURL query params or media type params (in Accept header) to configure the response to an HTTP request?
text
Body
copied!<p>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:</p> <pre><code>http://api.example.com/foo-book/ch1/?format=text&headings=false&footnotes=true </code></pre> <p>However, a more elegant RESTful way to indicate the desired response type (instead of the <code>format=text</code> URL query param) is to use the <code>Accept</code> header, for example:</p> <pre><code>Accept: text/plain; charset=utf-8 </code></pre> <p>Now, in addition to URLs, media types can take parameters per <a href="http://tools.ietf.org/html/rfc2046" rel="noreferrer">RFC 2046</a> and as seen in the ubiquitous <code>text/html; charset=utf-8</code> and in <code>Accept</code> headers like <code>audio/*; q=0.2</code>. It's also <a href="http://www.informit.com/articles/article.aspx?p=1566460" rel="noreferrer">shown</a> that vendor-crafted MIME types can define their own parameters like:</p> <pre><code>application/vnd.example-com.foo+json; version=1.0 application/vnd.example-info.bar+xml; version=2.0 </code></pre> <p>So for previously-registered MIME types like <code>text/html</code> or <code>application/json</code>, is it acceptable to include custom parameters for an application's needs? For example:</p> <pre><code>Accept: text/plain; charset=utf-8; headings=false; footnotes=true </code></pre> <p>This seems like an elegant RESTful solution, but it also seems like it would be violating something. <a href="http://tools.ietf.org/html/rfc2046#section-1" rel="noreferrer">RFC 2046 §1</a> says:</p> <pre><code>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. </code></pre> <p>Note this last sentence:</p> <pre><code>MIME implementations must also ignore any parameters whose names they do not recognize. </code></pre> <p>Does this mean that a client would be non-conforming if they recognized a <code>footnotes=true</code> parameter of the <code>text/plain</code> media type?</p>

Querying!

Guidance

An individual column

Larger individual text columns get their own page to allow for proper reading.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload