2.2.7.3.4 UpdateCollectionProperty Request
The purpose of the UpdateCollectionProperty request is to enable the value of a collection instance to be updated. AtomPub, as specified in [RFC5023], does not define operations on subcomponents of an Entry Resource. As such, this request type is not based on an AtomPub-defined [RFC5023] request.
UpdateCollectionProperty request MUST use the HTTP PUT method. Additionally, the URI specified by the client in the HTTP request line MUST be a valid data service URI that identifies a collection property instance, as specified in URI Format: Resource Addressing Rule (section 2.2.3). HTTP PATCH and MERGE methods are not valid with the UpdateCollectionProperty request.
The payload of the request MAY be formatted by using XML, JSON, or Verbose JSON format, according to the rules defined in Collection of Complex Type Instances (section 2.2.6.5.2) and Collection of EDMSimpleType Values (section 2.2.6.5.4) for XML, Collection of Primitive Values (section 7.3) and Collection of Complex Values (section 7.4) in [ODataJSON4.0] for JSON, or Collection of Complex Type Instances (section 2.2.6.3.5) and Collection of EDMSimpleType Values (section 2.2.6.3.7) for Verbose JSON. A server accepting a request of this type by using the PUT method MUST replace the entire value of the collection type addressed via the request URI with the value provided in the payload.
If the UpdateCollectionProperty request is successful, the response in OData 1.0 and OData 2.0 MUST have a 204 response code, as specified in [RFC2616], if the response contains no 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 RetrieveCollectionProperty request (section 2.2.7.2.6).
If the UpdateCollectionProperty 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 UpdateCollectionProperty request is defined as follows:
-
updateCollection-Req = updateCollection-ReqLine updateCollection-ReqHeaders CRLF updateCollection-ReqBody updateCollection-ReqLine = "PUT" SP entityTypeInstanceCollectionUri SP HTTP-Version CRLF updateCollection-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) updateCollection-ReqBody = <Collection of primitive values or collection of complex values formatted in JSON as per [ODataJSON4.0] sections 7.3 and 7.4> / <Collection of values formatted in Verbose JSON as per sections 2.2.6.3.5 or 2.2.6.3.7> / <Collection of values formatted in XML as per sections 2.2.6.5.6 and 2.2.6.5.7> entityTypeInstanceCollectionUri = <Any Resource Path identifying a Collection instance> ; see section 2.2.3 and section 2.2.3.5 – URI8
The syntax of a response to a successful UpdateComplexType Request is defined as follows:
-
updateCollection-Resp = Status-Line ; see [RFC2616] section 6.1.1 updateCollection-RespHeaders CRLF [updateCollection-RespBody] updateCollection-RespHeaders = DataServiceVersion ; see section 2.2.5.3 [Preference-Applied] ; see section 2.2.5.10 *(HTTP-Header-Types) updateCollection-RespBody = <Collection of primitive values or collection of complex values formatted in JSON as per [ODataJSON4.0] sections 7.3 and 7.4> / <Collection of values formatted in Verbose JSON as per sections 2.2.6.3.5 or 2.2.6.3.7> / <Collection of values formatted in XML as per sections 2.2.6.5.6 and 2.2.6.5.7>