2.2.7.2.1 RetrieveEntitySet Request

A RetrieveEntitySet request is used by a client to retrieve the entries in an AtomPub collection, as specified in [RFC5023], that maps to an EntitySet in the abstract data model used in this document, as described in Abstract Data Model (section 2.2.1). The base rules and semantics of this request type are defined by AtomPub, as specified in [RFC5023] section 5.2 -- Listing Collection Members. This section adds constraints to those defined in AtomPub for this request type.

According to [RFC5023] section 5.2, requests of this type MUST use the HTTP GET method and the URI specified by the client in the HTTP request line has to represent an AtomPub collection. Because a collection maps to an EntitySet in an Entity Data Model (EDM), the HTTP request line URI MUST be equal to any valid data service URI that identifies an EntitySet, as specified in URI Format: Resource Addressing Rules (section 2.2.3).

[RFC5023] section 9.2 states that the response body from such a request has to be an Atom Feed document. This document extends this rule to allow additional representations of a collection (or EntitySet) to be retrieved by a data service client. This document defines three representations of EntitySet: AtomPub as specified in Entity Set (as an Atom Feed Element) (section 2.2.6.2.1), Collection of Entities as specified in [ODataJSON4.0] section 12, and Verbose JSON as specified in Entity Set (as a Verbose JSON Array) (section 2.2.6.3.2).

If a RetrieveEntitySet request was successful, the response payload MUST contain the requested representation of the entities in the EntitySet identified in the request URI. The payload of such a response MUST be formatted using AtomPub, JSON, or Verbose JSON, according to the rules defined in AtomPub Format (section 2.2.6.2), JSON format [ODataJSON4.0] section 12, and Verbose JSON Format (section 2.2.6.3), respectively.

If the RetrieveEntitySet 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 syntax of a RetrieveEntitySet request is defined as follows:

 retrieveEntitySet-Req       = retrieveEntitySet-ReqLine  
                               retrieveEntitySet-ReqHeaders 
                               CRLF
                            
 retrieveEntitySet-ReqLine   = "GET" 
                               SP entitySetUri retrieveEntitySet-
                                  QueryOps  
                               SP HTTP-Version  
                               CRLF
  
 retrieveEntitySet-ReqHeaders = [DataServiceVersion]        
                                ; see section 2.2.5.3   
                                [MaxDataServiceVersion]     
                                ; see section 2.2.5.7   
                                [Accept]                    
                                ; see section 2.2.5.1   
                                *(HTTP-Header-Types)
  
 entitySetUri                  = ; see section 2.2.7.1.1   
  
 retrieveEntitySet-QueryOps    = ["?" (customQueryOption /sysQueryOption)
                                  *("&"customQueryOption / sysQueryOption)]
                                 ; see section 2.2.3.1 & section 2.2.3.6.1.5

The syntax of a response to a successful RetrieveEntitySet request is defined as follows:

 retrieveEntitySet-Resp       = Status-Line           
                                ; see [RFC2616] section 6.1.1  
                                  retrieveEntitySet-RespHeaders 
                                  CRLF
                                  retrieveEntitySet-RespBody
  
 retrieveEntitySet-RespHeaders= DataServiceVersion    
                                ; see section 2.2.5.3   
                                [Content-Type]        
                                ; see section 2.2.5.2   
                                [ETag]                
                                ; see section 2.2.5.4   
                                *(HTTP-Header-Types)
  
 retrieveEntitySet-RespBody   =  <Collectons of entities in JSON as per [ODataJSON4.0]
                                  section 12>
                                 / <Entity Set formatted as per section  
                                 2.2.6.2.1>
                                 / (begin-object 
                                    quotation-mark "d" quotation-mark 
                                    name-seperator 
                                    (entitySetInVJson / entitySetInVJson2)
                                    end-object)
                                    ; see section 2.2.6.3.2