3.1.4.3.1 Common Rules for Sending Retrieve Requests

  • Article

This section defines all the rules to which clients MUST adhere when sending Retrieve requests. Therefore, no additional rules for specific Retrieve request types are defined in this document.

Retrieve requests MUST adhere to the syntax rules that are specified in Retrieve Request Types (section 2.2.7.2).

As noted in Common Rules for all Requests (section 3.1.4.1), the client SHOULD specify the Accept (section 2.2.5.1) header or the Format system query option ($format) (section 2.2.3.6.1.5) to specify its preference regarding the content type used in the response.

If the higher layer causes the client to send a RetrieveEntitySet request or RetrieveEntity request, the media type(s) specified by the client in the Accept (section 2.2.5.1) header or the Format system query option (section 2.2.3.6.1.5) SHOULD include application/atom+xml (section 2.2.5.1.1), application/json (section 2.2.5.1.2), and/or application/json;odata=verbose (section 2.2.5.1.3). If the request type is RetrieveComplexType, RetrievePrimitiveProperty, or RetrieveLink, the media type(s) specified in the Accept (section 2.2.5.1) header or the $format query string option SHOULD include application/xml, application/json (section 2.2.5.1.2), and/or application/json;odata=verbose (section 2.2.5.1.3). If the request is a RetrieveValue or RetrieveMediaResource, the required media type(s) are data dependent and are not defined by this document. If the request is a RetrieveServiceDocument request, the required media types SHOULD include application/xml and application/atomsvc+xml, application/json (section 2.2.5.1.2), and/or application/json;odata=verbose (section 2.2.5.1.3). Finally, if the request is a RetrieveCount request, the media type specified in the Accept (section 2.2.5.1) header or the $format query string option MUST be text/plain.

If the retrieve request URI (provided by the higher layer) identifies an entity, ComplexType, primitive property, or property value, and the associated EntityType defines a concurrency token, the client MAY include an If-None-Match in the request. Even if the request URI includes a $expand query option, the concurrency token provided as the value of the If-None-Match header MUST be a token associated with the EntityType of the entity identified by the request URI. RetrieveLink requests MUST NOT include an If-None-Match or If-Match header.

If the retrieve request URI identifies a Media Resource, the request MAY include an If-None-Match (section 2.2.5.6) header.

For rules for processing responses, see Retrieve Request Types (section 2.2.7.2).