188.8.131.52.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 184.108.40.206).
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 220.127.116.11) request header. This document defines three such formats for links: XML, JSON, and Verbose JSON, as defined in Links (section 18.104.22.168.5), links formatted as a resource reference ([MS-ODATAJSON] section 2.1.23), and Links (section 22.214.171.124.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 126.96.36.199).
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 188.8.131.52 [MaxDataServiceVersion] ; see section 184.108.40.206 [Accept] ; see section 220.127.116.11 *(HTTP-Header-Types) entityTypeInstanceLinksUri = <Any Resource Path identifying a single Link or collection of Links> ; see section 2.2.3 and section 18.104.22.168 -- URI7 retrieveLink-QueryOps = ["?" (customQueryOption / formatQueryOp) *("&" customQueryOption)] ; see section 22.214.171.124
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 126.96.36.199 *(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 188.8.131.52.5> / quotation-mark "d" quotation-mark name-seperator <Representation of the links or link addressed in the request URI formatted as per section 184.108.40.206.10>