2.2.7.1.2 InsertLink Request
The purpose of the InsertLink request is to enable a new link to be created between two EntityType instances. AtomPub, as specified in [RFC5023], does not define a request of this type. Therefore, this request type is not based on an AtomPub-defined request, as specified in [RFC5023].
An InsertLink Request MUST use the HTTP POST method and the URI specified by the client
in the HTTP request line MUST be a valid data service URI, as
specified in URI Format:
Resource Addressing Rules (section 2.2.3), which identifies the collection of links between
an EntityType instance and an EntitySet.
The EntitySet MUST be related to the instance by a NavigationProperty
on the instance's EntityType, as specified in the URI7 grammar rule in Resource Path:
Semantics (section 2.2.3.5). For example, by using Appendix A: Sample Entity Data
Model and CSDL Document (section 6), the following is a valid URI
for requests of this type: http://host/service.svc/Customers('ALFKI')/$links/Orders.
In this context, the EntityType instance that is identified by the resource path segment immediately prior to the "$links" segment in the request URI is referred to as the source entity. Requests of this type MUST contain a request body (formatted as a link according to [MS-ODATAJSON] section 2.1.23, formatted according to the "linkVJson" rule in EDMSimpleType Property (section 2.2.6.3.8), or formatted according to the XML schema for a single link in EDMSimpleType property) that contains a URI that identifies the entity to be linked to from the source entity.
If the new link defined by a request of this type represents one direction of a bidirectional association, inserting the link (one direction of the bidirectional association) implies the opposite direction is also inserted.
If an InsertLink request is successful, the response MUST have a 204 status code, as specified in [RFC2616], and contain an empty response body.
If the InsertLink request is not successful (an error occurred while processing the request), the response MUST be formatted according to Error Response (section 2.2.8.1).
The syntax of an InsertLink request is defined as follows.
-
insertLink-Req = insertLink-ReqLine insertLink-ReqHeaders CRLF insertLink-ReqBody insertLink-ReqLine = "POST" SP entityTypeInstanceLinksUri insertLink-QueryOps SP HTTP-Version CRLF insertLink-ReqHeaders = [DataServiceVersion] ; see section 2.2.5.3 [MaxDataServiceVersion] ; see section 2.2.5.7 [Content-Type] ; see section 2.2.5.2 [Prefer] ; see section 2.2.5.9 *(HTTP-Header-Types) insertLink-ReqBody = <JSON representtation of a single link per [MS-ODATAJSON] section 2.1.23> / linkVJson ; see section 2.2.6.3.10 / <XML Representation of a single link as per the XML Schema in section 2.2.6.5.5> entityTypeInstanceLinksUri = <Any Resource Path identifying a collection of Links where the final URI segment is a navProperty (section 2.2.3.1) representing an Entity Set> ; see section 2.2.3.5 -- URI7 insertLink-QueryOps = ["?" customQueryOption *("&" customQueryOption)] ; see section 2.2.3.1
The syntax of a response to a successful InsertLink request is defined as follows.
-
insertLink-Resp = Status-Line ; see [RFC2616] section 6.1.1 insertLink-RespHeaders CRLF insertLink-RespHeaders = DataServiceVersion ; see section 2.2.5.3 [ETag] ; see section 2.2.5.4 [Preference-Applied] ; see section 2.2.5.10 *(HTTP-Header-Types)