2.2.7.2.10 RetrieveCount Request

Applies to the OData 2.0 and OData 3.0 protocols

The purpose of the RetrieveCount request is to enable the count of a collection of EntityType instances or a single EntityType instance to be retrieved by the client. AtomPub, as specified in [RFC5023], does not define a request of this type. Therefore, this request type is not based on an AtomPub-defined [RFC5023] request.

A RetrieveCount Request MUST use the HTTP GET method and the URI specified by the client in the HTTP request line MUST be a valid data service URI that identifies a collection of EntityType instances, as specified in URI Format: Resource Addressing Rules (section 2.2.3).

If the RetrieveValue Request was successful, the response MUST have a 2xx status code, as specified in [RFC2616], and the response body MUST be formatted as specified in EDMSimpleType Property (section 2.2.6.4.1).

If the RetrieveValue Request is not successful (for example, an error occurred while processing the request), the response MUST be formatted according to Error Response (section 2.2.8.1).

The RetrieveCount Request is supported only in the OData 2.0 and OData 3.0 protocols.

The syntax of a RetrieveCount Request is defined as follows:

 retrieveCount-Req         = retrieveCount-ReqLine
                             retrieveCount-ReqHeaders
                             CRLF
  
 retrieveCount-ReqLine     = "GET"
                             SP entitySetUri [/ entityTypeInstanceUri]
                                "/$count"
                                retrieveCount-QueryOps
                             SP HTTP-Version
                             CRLF
  
 retrieveCount-ReqHeaders  = [DataServiceVersion]        ; see section 2.2.5.3
                             [MaxDataServiceVersion]     ; see section 2.2.5.7
                             *(HTTP-Header-Types)
  
 entitySetUri                  = ; see section 2.2.7.1.1   
  
 entityTypeInstanceUri = ; see section 2.2.7.4.1    
  
 retrieveCount-QueryOps    = ["?" customQueryOption 
                                 /sysQueryOption *("&"
                                  customQueryOption 
                                 / sysQueryOption)]
                                 ; see section 2.2.3.1

The syntax of a response to a successful RetrieveCount Request is defined as follows:

 retrieveCount-Resp       = Status-Line                 ; see [RFC2616] section 6.1.1
                            retrieveCount-RespHeaders
                            CRLF
                            retrieveCount-RespBody
  
 retrieveCount-RespHeaders= DataServiceVersion          ; see section 2.2.5.3
                            [Content-Type]              ; see section 2.2.5.2
                            *(HTTP-Header-Types)
  
 retrieveCount-RespBody   = <Count value formatted as per section 2.2.6.4.1>