2.2.7.2.6 RetrieveCollectionProperty Request

The purpose of the RetrieveCollectionProperty request is to enable the value of a collection property on an EntityType instance to be retrieved by a client. AtomPub, as specified in [RFC5023], does not define operations on subcomponents of an entry resource. As such, this request type is not based on any AtomPub-defined [RFC5023] request.

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

If the RetrieveCollectionProperty request is successful, the response MUST have a 2xx status code, as specified in [RFC2616]. The payload of such a response MUST be formatted by using XML as defined in Collection of EDMSimpleType Values (section 2.2.6.5.3), JSON as defined in Collection of Primitive Values ([ODataJSON4.0] section 7.3), or Verbose JSON as defined in Collection of EDMSimpleType Values (section 2.2.6.3.7).

If the RetrieveCollectionProperty request is not successful, the response MUST be formatted according to Error Response (section 2.2.8.1).

The syntax of a RetrieveCollectionProperty request is defined as follows:

 retrieveCollection-Req          = retrieveCollection-ReqLine
                           retrieveCollection-ReqHeaders
                           CRLF
  
 retrieveCollection-ReqLine      = "GET"
                           SP entityTypeInstanceCollectionPropertyUri 
                           SP HTTP-Version
                           CRLF
  
 retrieveCollection-ReqHeaders   = [DataServiceVersion]        ; see section 2.2.5.3
                           [MaxDataServiceVersion]     ; see section 2.2.5.7
                           [If-None-Match]             ; see section 2.2.5.6
                           [Accept]                    ; see section 2.2.5.1
                           *(HTTP-Header-Types)
  
 entityTypeInstanceCollectionPropertyUri = <Any Resource Path identifying a Collection
                                    property on an Entity Type instance>
                                    ; see section 2.2.3 and section 2.2.3.5 – URI18

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

 retrieveCollection-Resp         =  Status-Line                 ; see [RFC2616] section 6.1.1
                            retrieveCollection-RespHeaders
                            CRLF
                            retrieveCollection-RespBody
  
 retrieveCollection-RespHeaders  =  DataServiceVersion          ; see section 2.2.5.3
                            [ETag]                      ; see section 2.2.5.4
                            [Content-Type]              ; see section 2.2.5.2
                            *(HTTP-Header-Types)
  
 retrieveCollection-RespBody     =  <Collection of primitive values and collection of complex
                                     values formatted in JSON as per [ODataJSON4.0]
                                     sections 7.3 and 7.4, respectively>
                                    / <Collection property values formatted in
                                       Verbose JSON as per sections 2.2.6.3.5 and 2.2.6.3.7>
                                    / <Collection property values formatted in XML as
                                       per sections 2.2.6.5.6 and 2.2.6.5.7>