Share via

2.2.5.9 Prefer

  • Article

A Prefer header is included in a request to state the client’s preferred, but not required, server behavior (that is, a hint to the server). The Prefer header MAY be included on any request type (within a standalone or batch request), and a server MAY honor the header for HTTP POST, PUT, PATCH, and MERGE requests. A Prefer header with a value of “return-content” MUST NOT be specified on a DELETE request, a batch request as a whole, or a PUT request to update a named stream.

The syntax of the Prefer header is defined as follows:

 Prefer       =  "Prefer" ":" preference 
  
 preference   =  "return-no-content" |
                 "return-content" |
                 preference-extension
  
 preference-extension =  prefer-params *( ";" prefer-params ])
 prefer-params =  token [ "=" ( token | quoted-string )

A header value of "return-no-content" indicates that the client prefers that the server not include an entity representing the current state of the resource in the response to a successful request. If the value is “return-no-content”, the server MAY choose to return an empty response payload with status code 204.

A header value of "return-content" indicates that the client prefers that the server include an entity that represents the current state of the resource in the response to a successful request. If the value is “return-content”, the representation (as requested by the Accept header) of the current state of the inserted or updated resource MAY be returned in the body of the response. If it is included, the resource MUST be formatted as if it was being retrieved with a GET operation. However, in the case of a PUT request to a media stream, the response is formatted as if it is the response to a successful POST operation with the specified content.

When the Prefer header is included with a request that uses POST tunneling, as specified in section 2.2.5.8, the preference is to be applied to the tunneled request.

Preference values of the prefer header other than return-content or return-no-content are not defined by this specification. If any of the preference values of the Prefer header are not recognized by the service, those values of the Prefer header MUST be ignored by the server and the server MUST continue processing the request as if the Prefer header was not specified.