2.2.7.2.9 RetrieveLink Request

The purpose of the RetrieveLink request is to enable the links representing the relationships from one EntityType instance to another or from one EntityType instance to all others in a specified EntitySet to be retrieved by a 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 RetrieveLink 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 the links from one EntityType instance to another or from one EntityType instance to all other entities in a specified EntitySet, as described in the URI7 grammar rule in Resource Path: Semantics (section 2.2.3.5).

If the RetrieveLink request was successful, the response MUST have a 2xx status code, as specified in [RFC2616]. The response payload MUST contain a representation of the set of links or single link identified by the request URI. A client states the desired response payload format using the Accept (section 2.2.5.1) request header. This document defines three such formats for links: XML, JSON, and Verbose JSON, as defined in Links (section 2.2.6.5.5), links formatted as a resource reference ([MS-ODATAJSON] section 2.1.23), and Links (section 2.2.6.3.10), respectively.

If the RetrieveLink 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 RetrieveLink Request is defined as follows:

 retrieveLink-Req          = retrieveLink-ReqLine
                             retrieveLink-ReqHeaders
                             CRLF
  
 retrieveLink-ReqLine      = "GET"
                             SP entityTypeInstanceLinksUri retrieveLink-QueryOps
                             SP HTTP-Version
                             CRLF
  
 retrieveLink-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)
  
 entityTypeInstanceLinksUri = <Any Resource Path identifying a single Link or collection
                               of Links>
                               ; see section 2.2.3 and section 2.2.3.5 -- URI7
  
 retrieveLink-QueryOps     = ["?" (customQueryOption / formatQueryOp) 
                              *("&" customQueryOption)]
                             ; see section 2.2.3.1

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

 retrieveLink-Resp         =  Status-Line              ; see [RFC2616] section 6.1.1
                              retrieveLink-RespHeaders
                              CRLF
                              retrieveLink-RespBody
  
 retrieveLink-RespHeaders  =  DataServiceVersion       ; see section 2.2.5.3
                              *(HTTP-Header-Types)
  
 retrieveLink-RespBody     =  <Representation of the links or link addressed in the
                               request URI formatted as per [MS-ODATAJSON] section 2.1.23>
                              / <Representation of the links or link addressed in the
                                 request URI formatted as per section 2.2.6.5.5>
                              / quotation-mark "d" quotation-mark
                                name-seperator
                                <Representation of the links or link addressed in the
                                 request URI formatted as per section 2.2.6.3.10>