2.2.7.3.1 UpdateEntity Request

An UpdateEntity Request is used by a client to update an existing AtomPub Entry Resource, as specified in [RFC5023], that maps to an EntityType instance in the abstract data model used in this document, as described in Abstract Data Model (section 2.2.1). The base rules and semantics of this request type are defined by AtomPub, as specified in [RFC5023] section 5.4. This section adds constraints to those defined in AtomPub for this request type.

As in [RFC5023] section 5.4.2, requests of this type use the HTTP PUT method, and the URI specified by the client in the HTTP request line represents an AtomPub entry resource. Given that an entry resource maps to an EntityType instance in an Entity Data Model (EDM), the HTTP request line URI MUST be equal to any valid data service URI that identifies an EntityType instance, as described in URI Format: Resource Addressing Rules (section 2.2.3). Additionally, this specification allows UpdateEntity requests to use the MERGE method (as defined in PATCH/MERGE (section 2.2.4.1)) or PATCH method (as defined in [RFC5789]) instead of PUT to specify that a merge-based update is to be performed.

[RFC5023] section 5.4.2 states that the request body can be an AtomPub entry resource (that maps to an EntityType instance in an EDM) that is represented as an Atom entry document. This document extends this rule to allow additional representations of an entry resource to be used. This document defines three such representations: 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). A client SHOULD specify the representation used in the request body by including a Content-Type header in the request.

When the request body is a representation of an Entry Resource (EntityType instance in EDM terms), the client can specify if the resource/entity (in addition to being updated) is to be automatically linked to other already existing entities in the data service that are related through associations such that the opposite association end has a cardinality of 1 or 0-or-1. Such linking MUST only be supported if the EntityType of the to-be-edited entity defines a NavigationProperty that identifies a single EntityType instance. For example, an existing employee entity might need to be rebounded to an existing manager entity in a human resources management focused data service.

To rebind the entity to an existing entity, the client MUST include the required binding information in the representation of the associated NavigationProperty in the request payload.

To bind the entity to an existing entity using the Atom format, the NavigationProperty MUST be represented as specified in Navigation Property (section 2.2.6.2.4) with one exception: the href attribute of the atom:link element is equal the URI that identifies the existing entity that is the target of the link.

To bind the new entity to an existing entity by using the preferred OData 3.0 JSON format, see [ODataJSON4.0] section 8.5.

To bind the new entity to an existing entity by using the Verbose JSON format, the NavigationProperty MUST represent the entity that is the target of the link by using the Inline Representation (section 2.2.6.3.9.1) of a NavigationProperty with the single inlined entity represented using only the "__metadata" name/value pair (the properties of the inlined entity SHOULD NOT be provided). If the inlined entity's properties are provided, they MUST be ignored by the data service.

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 the response body to a RetrieveEntity request (section 2.2.7.2.2).

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

The syntax of an UpdateEntity request is defined as follows:

 updateEntity-Req         = updateEntity-ReqLine  
                            updateEntity-ReqHeaders 
                            CRLF
                            updateEntity-ReqBody  
  
 updateEntity-ReqLine     = ("PUT" / "MERGE"/ "PATCH") 
                            SP entityTypeInstanceUri updateEntity-QueryOps
                            SP HTTP-Version CRLF
  
 updateEntity-ReqHeaders  = [DataServiceVersion]     ; see section 2.2.5.3
                            [MaxDataServiceVersion]  ; see section 2.2.5.7
                            [If-Match]               ; see section 2.2.5.5
                            [Content-Type]           ; see section 2.2.5.2
                            [Prefer]                 ; see section 2.2.5.9
                            *(HTTP-Header-Types)
  
 entityTypeInstanceUri = ; see section 2.2.7.4.1   
  
 updateEntity-QueryOps    = ["?" (customQueryOption / filterQueryOp) *("&" customQueryOption)]
                            ; see section 2.2.3.1   
  
 updateEntity-ReqBody     = <Entity in JSON format as per [ODataJSON4.0] section 6>
                            / <entityTypeInVJson       ; see section 2.2.6.3.3>
                            / <Entity Type in Atom format as per section 2.2.6.2.2>
                            / <Entity Type with Property Mapping in Atom format as per section 
                                2.2.6.2.2.1>

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

 updateEntity-Resp        = Status-Line           ; see [RFC2616] section 6.1.1  
                            updateEntity-RespHeaders 
                            CRLF
                            [updateEntity-RespBody]
  
 updateEntity-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)
 updateEntity-RespBody     =  <Entity (possibly with expanded navigation properties) 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