2.2.7.3.6 UpdateLink Request

The purpose of the UpdateLink request is to enable a Link to be established between two EntityType instances. AtomPub [RFC5023] does not define a request of this type. Therefore, this request type is not based on an AtomPub-defined [RFC5023] request.

An UpdateLink request MUST use the HTTP PUT, PATCH, or MERGE method (as specified in PATCH/MERGE (section 2.2.4.1)). Addtionally, the URI specified by the client in the HTTP request line MUST be a valid data service URI that identifies a single link between two EntityType instances, as described in URI Format: Resource Addressing Rules (section 2.2.3).

For example, when using the model described in Appendix A: Sample Entity Data Model and CSDL Document (section 6), http://host/service.svc/Orders(1)/$links/Customer is a valid URI for updating which Customer is associated with Orders(1). However, http://host/service.svc/Customers('ALFKI')/$links/Orders(1) is not valid for an UpdateLink request because the navigation property on Customer identifies a collection of Orders.

In this context, the EntityType instance 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 resource reference according to [MS-ODATAJSON] section 2.1.23, formatted according to the "linkVJson" rule in Links (section 2.2.6.3.10), or formatted according to the XML schema for a single link in Links (section 2.2.6.5.5)) that contains a URI that identifies the EntityType instance to be linked to from the source entity.

If the UpdateEntity request is successful, the response in OData 1.0 and OData 2.0 MUST have a 204 response code, as specified in [RFC2616], and have 0 bytes in the response body, unless a Prefer header (section 2.2.5.9) has been specified to request content. When an OData 1.0 or OData 2.0 request contains a Prefer header value that requests content or when OData 3.0 is used, the response MAY have a 200 response code, as specified in [RFC2616], and a response body that MUST be formatted the same as a response body to an RetrieveLink request (section 2.2.7.2.9).

If the UpdateLink request is not successful (for example, if an error occurs during request processing), the response MUST be formatted according to Error Response (section 2.2.8.1).

The syntax of an UpdateLink request is defined as follows:

 updateLink-Req          =   updateLink-ReqLine
                             updateLink-ReqHeaders
                             CRLF
                             updateLink-ReqBody
  
 updateLink-ReqLine      =   "PUT" / "MERGE"/ "PATCH
                             SP entityTypeInstanceSingleLinkUri updateLink-QueryOps
                             SP HTTP-Version
                             CRLF
                             updateLink-ReqBody
  
 updateLink-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)
  
 updateLink-ReqBody      =   <Resource reference formatted in JSON as 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.3>
  
 entityTypeInstanceSingleLinkUri =  ; section 2.2.7.4.2
  
 updateLink-QueryOps     = ["?" customQueryOption *("&" customQueryOption)]
                             ; see section 2.2.3.1

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

 updateLink-Resp         =    Status-Line              ; see [RFC2616] section 6.1.1
                              updateLink-RespHeaders
                              CRLF
                              [updateLink-RespBody]
  
 updateLink-RespHeaders  =    DataServiceVersion       ; see section 2.2.5.3
                              [Preference-Applied]         ; see section 2.2.5.10   
                              *(HTTP-Header-Types)
  
 updateLink-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>