2.2.7.2.2 RetrieveEntity Request

A RetrieveEntity request is used by a client to retrieve an AtomPub entry resource, as specified in [RFC5023], and potentially related entities that map to EntityType instances, as described in Abstract Data Model (section 2.2.1).

Requests of this type MUST use the HTTP GET method and the URI specified by the client in the HTTP request line MUST represent an AtomPub entry resource. Because an entry resource maps to an EntityType in an Entity Data Model (EDM), the HTTP request line URI MUST be any valid data service URI that identifies an EntityType instance, as defined in URI Format: Resource Addressing Rules (section 2.2.3). A client will typically obtain such a URI after parsing one of the EntityType instances serialized in the response payload from a prior RetrieveEntitySet request, as specified in Retrieve Request Types (section 2.2.7.2). When using the AtomPub format in a RetrieveEntitySet request, such a URI is typically obtained from the "edit" or "self" URIs described in AtomPub, as specified in [RFC5023] section 11.1 (The "edit" Link Relation), [RFC4287] section 4.2.7.2, and Entity Type (as an Atom Entry Element) (section 2.2.6.2.2). Using Verbose JSON in the RetrieveEntitySet request, the URI is obtained from the metadata name/value pair of a JSON object representing an entity, as described in Entity Type (as a Verbose JSON object) (section 2.2.6.3.3). For information about obtaining the URI for the RetrieveEntitySet request in the preferred OData 3.0 JSON format, see [ODataJSON4.0] section 4.5.8.

AtomPub [RFC5023] describes retrieving an AtomPub entry resource, which maps to an EntityType instance in an EDM, in an HTTP response payload that MUST be represented as an Atom entry document, as specified in [RFC4287] section 4.1.2. This document extends that behavior to allow additional representations of an entry resource to be retrieved by a data service client. A client states the desired response payload format by using the Accept (section 2.2.5.1) request header. This document defines three representations of EntityTypes: entity type as an Atom Entry element (section 2.2.6.2.2), entity as a JSON object ([ODataJSON4.0] section 6), and entity type as a Verbose JSON object (section 2.2.6.3.3).

If the RetrieveEntity request was successful, the response payload MUST contain the requested representation of the EntityType instance identified in the request URI. The payload of such a response MUST be formatted by using Atom, JSON, or Verbose JSON according to the rules defined in Entity Type (as an Atom Entry Element) (section 2.2.6.2.2), Entity (as a JSON object) ([ODataJSON4.0] section 6), and Entity Type (as a Verbose JSON object) (section 2.2.6.3.3).

If the RetrieveEntity 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 RetrieveEntity request is defined as follows:

 retrieveEntity-Req       = retrieveEntity-ReqLine  
                            retrieveEntity-ReqHeaders 
                            CRLF
                            
 retrieveEntity-ReqLine   = "GET"   
                            SP entityTypeInstanceUri retrieveEntity-
                               QueryOps  
                            SP HTTP-Version  
                            CRLF
  
 retrieveEntity-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)
  
 entityTypeInstanceUri = ; see section 2.2.7.4.1    
  
 retrieveEntity-QueryOps   = ["?"(customQueryOption /sysQueryOption)
                              *("&" customQueryOption / sysQueryOption)]

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

 retrieveEntity-Resp         =  Status-Line           
                                ; see [RFC2616] section 6.1.1  
                                retrieveEntity-RespHeaders 
                                CRLF
                                retrieveEntity-RespBody
  
 retrieveEntity-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)
  
 ; Responses including related entities were requesting using the 
 ; $expand query string operator defined in section 2.2.3.6.1
                                    
 retrieveEntity-RespBody     =  <Entity (possibly with Expanded Navigation Property)
                                 formatted by using JSON as per [ODataJSON4.0]
                                 sections 6 and 8.3>
                                / <Entity Type instance (possibly with
                                   related instances) formatted by using
                                   Atom as per sections 
                                    2.2.6.2.2 and 2.2.6.2.6.1>
                                / (begin-object 
                                   quotation-mark "d" quotation-mark 
                                   name-seperator 
                                   entityTypeInVJson
                                   end-object)
                                   ; see section 2.2.6.3.3 &
                                   ; 2.2.6.3.9.1