A REST API can return the resource representation in many formats – to be more specific MIME-types. A client application or browser can request for any supported MIME type in HTTP Accept header. Technically, Accept
header can have multiple values in form of comma separated values.
For example, an Accept
header requesting for text/html
or application/xml
formats can be set as:
Accept : text/html,application/xml
The ‘q’ Parameter
Sometimes client may want to set their preferences when requesting multiple MIME
types. To set this preference, q
parameter (relative quality factor) is used.
Value of q
parameter can be from 0 to 1. 0 is lowest value (i.e. least preferred) and 1 is highest (i.e. most preferred).
A sample usage can be:
Accept : text/html, application/xml;q=0.9, */*;q=0.8
In above example, client is indicating the server that it will prefer to have the response in text/html
format, first. It server does not support text/html
format for requested resource than it shall send application/xml
format. If none of both formats are available, then send the response in whatever format it support (*/*
).
- One of the benefit of the ‘q’ parameter is to minimize the client-server interactions, which could have happened due to failed content negotiations.
- It also allows clients to receive content types of which they may not be aware, an asterisk “*” may be used in place of either the second half of MIME type value or both halves.
Here’s how the HTTP spec defines it:
If there are two MIME types for the same q
value, then a more specific type, between both, wins.
For example if both application/xml
and */*
had a preference of 0.9 then application/xml
will be served by the server.
Accept
header field is present, then it is assumed that the client accepts all media types. If an Accept
header field is present, and if the server cannot send a response which is acceptable according to the combined Accept
field value, then the server SHOULD send a 406 (not acceptable)
response.
captainhb says
one question arises in :
Accept : text/html, application/xml;q=0.9, */*;q=0.8
what is the meaning of the last q parameter (q=0.8) in this Accept header?
Admin says
That is the whole thing discussed in this article.
Dave says
I’m also confused by this; It seems to me that;
Accept : text/html, application/xml;q=0.9, */*
would suffice.
I believe that server-side, that first “q” parameter would be overwritten by the second. The server would see the value 0.8 only. Unless you’re parsing the query string directly I suppose.
Other than that, I’m finding this site to be a fantastic resource.
Admin says
‘q’ parameter is parsed by the framework for content negotiation. They do not overwrite each other. They simply represent the preference of one media type over other.
Max says
Perhaps I’m missing something; what’s the point of ranking your Accept header items when they’re already ordered in a comma-separated value?
Admin says
Any sequence is possible for ‘Accept’ header media types. Assigning ‘q’ value safegaurds the application from accidental mistakes.