REST API Tutorial

  • REST
  • JSON
  • Dark Mode

‘q’ Parameter in HTTP ‘Accept’ Header

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 ‘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:

Each media-range MAY be followed by one or more accept-params, beginning with the “q” parameter for indicating a relative quality factor. The first “q” parameter (if any) separates the media-range parameter(s) from the accept-params. Quality factors allow the user or user agent to indicate the relative degree of preference for that media-range, using the ‘q’ value scale from 0 to 1. The default value is 1.

If there are two MIME types for given same q value, then 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.

If no 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.

TwitterFacebookLinkedinReddit

6
Leave a Reply

This comment form is under antispam protection
2 Comment threads
4 Thread replies
0 Followers
 
Most reacted comment
Hottest comment thread
4 Comment authors
This comment form is under antispam protection
  Subscribe  
newest oldest most voted
Notify of
captainhb

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?

Vote Up0Vote Down  Reply
6 months ago
Admin

That is the whole thing discussed in this article.

Vote Up0Vote Down  Reply
6 months ago
Dave

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.

Vote Up0Vote Down  Reply
1 month ago
Admin

‘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.

Vote Up0Vote Down  Reply
1 month ago
Max

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?

Vote Up0Vote Down  Reply
7 months ago
Admin
Accept : text/html;q=0.8, application/xml;q=0.5, */*;q=0.4

Any sequence is possible for ‘Accept’ header media types. Assigning ‘q’ value safegaurds the application from accidental mistakes.

Vote Up0Vote Down  Reply
7 months ago

Learn REST

  • What is REST?
  • REST Constraints
  • REST Resource Naming Guide

Guides

  • Caching
  • Compression
  • Content Negotiation
  • HATEOAS
  • Idempotence
  • Security Essentials
  • Versioning
  • Statelessness

Tech – How To

  • REST API Design Tutorial
  • Create REST APIs with JAX-RS 2.0

FAQs

  • PUT vs POST
  • N+1 Problem
  • ‘q’ Parameter

Resources

  • Comparing SOAP vs REST APIs
  • HTTP Methods
  • Richardson Maturity Model
  • HTTP Response Codes
    • 200 (OK)
    • 201 (Created)
    • 202 (Accepted)
    • 204 (No Content)

References

  • The dissertation by Roy Thomas Fielding
  • Uniform Resource Identifier (URI, URL, URN) [RFC 3986]
  • Internet MediaTypes
  • Web Application Description Language (WADL)

Meta Links

  • About
  • Contact Us
  • Privacy Policy

Blogs

  • How To Do In Java
Creative Commons License
This work by RESTfulAPI.net is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
wpDiscuz