From 6371a7edc62170ac3cf3e83ad06e45e1ba93079c Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 9 Nov 2023 10:18:27 +0100 Subject: [PATCH] Heiko's suggestions --- docs/odata-protocol/odata-protocol.html | 10 +++++----- docs/odata-protocol/odata-protocol.md | 15 +++++---------- odata-protocol/11.4 Data Modification.md | 15 +++++---------- 3 files changed, 15 insertions(+), 25 deletions(-) diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index e8df412cb..a7a044f37 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -1805,7 +1805,7 @@

1

If an update specifies both a binding to a single-valued navigation property and a dependent property that is tied to a key property of the principal entity according to the same navigation property, then the dependent property is ignored, and the relationship is updated according to the value specified in the binding.

If the entity being updated is open, then additional values for properties beyond those specified in the metadata or returned in a previous request MAY be sent in the request body. The service MUST treat these as dynamic properties.

If the entity being updated is not open, then additional values for properties beyond those specified in the metadata or returned in a previous request SHOULD NOT be sent in the request body. The service MUST fail if it is unable to persist all updatable property values specified in the request.

-

Upon successful completion the service responds with either 200 OK and a representation of the updated entity, or 204 No Content. The client may request that the response SHOULD include a body by specifying a Prefer header with a value of return=representation, or by specifying the system query options $select or $expand. If the service uses ETags for optimistic concurrency control, the entities in the response MUST include ETags.

+

Upon successful completion the service responds with either 200 OK and a representation of the updated entity, or 204 No Content. The client may request that the response SHOULD include a body by specifying a return=representation preference, or by specifying the system query options $select or $expand. If the service uses ETags for optimistic concurrency control, the entities in the response MUST include ETags.

Update requests with an OData-Version header with a value of 4.0 MUST NOT contain related entities as inline content. Such requests MAY contain binding information for navigation properties. For single-valued navigation properties this replaces the relationship. For collection-valued navigation properties this adds to the relationship.

Payloads with an OData-Version header with a value of 4.01 or greater MAY include nested entities and entity references that specify the full set of to be related entities, or a nested delta payload representing the related entities that have been added, removed, or changed. Such a request is referred to as a “deep update”. If the nested collection is represented identical to an expanded navigation property, then the set of nested entities and entity references specified in a successful update request represents the full set of entities to be related according to that relationship and MUST NOT include added links, deleted links, or deleted entities.

@@ -1913,7 +1913,7 @@

11.4.7.1 Create a Media Entity

A POST request to a media entity’s entity set creates a new media entity. The request body MUST contain the media value (for example, the photograph) whose media type MUST be specified in a Content-Type header. The request body is always interpreted as the media value, even if it has the media type of an OData format supported by the service. It is not possible to set the structural properties of the media entity when creating the media entity.

Upon successful completion, the response MUST contain Location header that contains the edit URL of the created media entity.

-

Upon successful completion the service responds with either 201 Created, or 204 No Content if the request included a Prefer header with a value of return=minimal.

+

Upon successful completion the service responds with either 201 Created, or 204 No Content if the request included a return=minimal preference.

11.4.7.2 Update a Media Entity Stream

A successful PUT request to the media edit URL of a media entity changes the media stream of the entity.

If the entity includes an ETag value for the media stream, the client MUST include an If-Match header with the ETag value.

@@ -1966,7 +1966,7 @@

A successful PUT request to the edit URL for a primitive property updates the value of the property. The message body MUST contain the new value, formatted as a single property according to the specified format.

A successful PUT request to the edit URL for the raw value of a primitive property updates the property with the raw value specified in the payload. The payload MUST be formatted as an appropriate content type for the raw value of the property.

The same rules apply whether this is a regular property or a dynamic property.

-

Upon successful completion the service responds with either 200 OK or 204 No Content. The client may request that the response SHOULD include a body by specifying a Prefer header with a value of return=representation.

+

Upon successful completion the service responds with either 200 OK or 204 No Content. The client may request that the response SHOULD include a body by specifying a return=representation preference.

Services MUST return an error if the property is not updatable.

11.4.9.2 Set a Value to Null

A successful DELETE request to the edit URL for a structural property, or to the edit URL of the raw value of a primitive property, sets the property to null. The request body is ignored and should be empty.

@@ -1980,7 +1980,7 @@

200 OK or 204 No Content. The client may request that the response SHOULD include a body by specifying a Prefer header with a value of return=representation.

+

Upon successful completion the service responds with either 200 OK or 204 No Content. The client may request that the response SHOULD include a body by specifying a return=representation preference.

Services MUST return an error if the property is not updatable.

11.4.9.4 Update a Collection Property

A successful PUT request to the edit URL of a collection property updates that collection. The message body MUST contain the desired new value, formatted as a collection property according to the specified format.

@@ -1988,7 +1988,7 @@

A successful POST request to the edit URL of a collection property adds an item to the collection. The body of the request MUST be a single item to be added to the collection. If the collection is ordered, the item is added to the end of the collection, and if the collection supports positional insert $index MAY be used to specify the insert position.

A successful DELETE request to the edit URL of a collection property deletes all items in that collection.

Since collection members have no individual identity, PATCH is not supported for collection properties.

-

Upon successful completion the service responds with either 200 OK and a representation of the updated collection, or 204 No Content. The client may request that the response SHOULD include a body by specifying a Prefer header with a value of return=representation.

+

Upon successful completion the service responds with either 200 OK and a representation of the updated collection, or 204 No Content. The client may request that the response SHOULD include a body by specifying a return=representation preference.

Services MUST return an error if the property is not updatable.

11.4.10 Managing Members of an Ordered Collection

Collections annotated with the Core.Ordered term (see OData-VocCore) have a stable order. Members of an ordered collection of primitive and complex types can be individually updated or deleted by invoking an update operation against the URL of the collection appended by a segment containing the zero-based ordinal of the item within the collection. A negative ordinal number indexes from the end of the collection, with -1 representing the last item in the collection.

diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md index f6385794f..e6b38f590 100644 --- a/docs/odata-protocol/odata-protocol.md +++ b/docs/odata-protocol/odata-protocol.md @@ -4343,8 +4343,7 @@ Upon successful completion the service responds with either [`200 OK`](#ResponseCode200OK) and a representation of the updated entity, or [`204 No Content`](#ResponseCode204NoContent). The client may request that the response SHOULD include a body by specifying a -[`Prefer`](#Preferencereturnrepresentationandreturnminimal) header with a value of -[`return=representation`](#Preferencereturnrepresentationandreturnminimal), or by +[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference, or by specifying the system query options [`$select`](#SystemQueryOptionselect) or [`$expand`](#SystemQueryOptionexpand). If the service uses ETags for @@ -4645,8 +4644,7 @@ entity. Upon successful completion the service responds with either [`201 Created`](#ResponseCode201Created), or [`204 No Content`](#ResponseCode204NoContent) if the request included a -[`Prefer`](#Preferencereturnrepresentationandreturnminimal) header with a value of -[`return=minimal`](#Preferencereturnrepresentationandreturnminimal). +[`return=minimal`](#Preferencereturnrepresentationandreturnminimal) preference. #### 11.4.7.2 Update a Media Entity Stream @@ -4794,8 +4792,7 @@ Upon successful completion the service responds with either [`200 OK`](#ResponseCode200OK) or [`204 No Content`](#ResponseCode204NoContent). The client may request that the response SHOULD include a body by specifying a -[Prefer](#Preferencereturnrepresentationandreturnminimal) header with a value of -[`return=representation`](#Preferencereturnrepresentationandreturnminimal). +[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference. Services MUST return an error if the property is not updatable. @@ -4846,8 +4843,7 @@ Upon successful completion the service responds with either [`200 OK`](#ResponseCode200OK) or [`204 No Content`](#ResponseCode204NoContent). The client may request that the response SHOULD include a body by specifying a -[Prefer](#Preferencereturnrepresentationandreturnminimal) header with a value of -[`return=representation`](#Preferencereturnrepresentationandreturnminimal). +[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference. Services MUST return an error if the property is not updatable. @@ -4878,8 +4874,7 @@ Upon successful completion the service responds with either [`200 OK`](#ResponseCode200OK) and a representation of the updated collection, or [`204 No Content`](#ResponseCode204NoContent). The client may request that the response SHOULD include a body by specifying a -[Prefer](#Preferencereturnrepresentationandreturnminimal) header with a value of -[`return=representation`](#Preferencereturnrepresentationandreturnminimal). +[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference. Services MUST return an error if the property is not updatable. diff --git a/odata-protocol/11.4 Data Modification.md b/odata-protocol/11.4 Data Modification.md index 92dcb3fcc..99b0abd87 100644 --- a/odata-protocol/11.4 Data Modification.md +++ b/odata-protocol/11.4 Data Modification.md @@ -393,8 +393,7 @@ Upon successful completion the service responds with either [`200 OK`](#ResponseCode200OK) and a representation of the updated entity, or [`204 No Content`](#ResponseCode204NoContent). The client may request that the response SHOULD include a body by specifying a -[`Prefer`](#Preferencereturnrepresentationandreturnminimal) header with a value of -[`return=representation`](#Preferencereturnrepresentationandreturnminimal), or by +[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference, or by specifying the system query options [`$select`](#SystemQueryOptionselect) or [`$expand`](#SystemQueryOptionexpand). If the service uses ETags for @@ -695,8 +694,7 @@ entity. Upon successful completion the service responds with either [`201 Created`](#ResponseCode201Created), or [`204 No Content`](#ResponseCode204NoContent) if the request included a -[`Prefer`](#Preferencereturnrepresentationandreturnminimal) header with a value of -[`return=minimal`](#Preferencereturnrepresentationandreturnminimal). +[`return=minimal`](#Preferencereturnrepresentationandreturnminimal) preference. #### ##subsubsubsec Update a Media Entity Stream @@ -844,8 +842,7 @@ Upon successful completion the service responds with either [`200 OK`](#ResponseCode200OK) or [`204 No Content`](#ResponseCode204NoContent). The client may request that the response SHOULD include a body by specifying a -[Prefer](#Preferencereturnrepresentationandreturnminimal) header with a value of -[`return=representation`](#Preferencereturnrepresentationandreturnminimal). +[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference. Services MUST return an error if the property is not updatable. @@ -897,8 +894,7 @@ Upon successful completion the service responds with either [`200 OK`](#ResponseCode200OK) or [`204 No Content`](#ResponseCode204NoContent). The client may request that the response SHOULD include a body by specifying a -[Prefer](#Preferencereturnrepresentationandreturnminimal) header with a value of -[`return=representation`](#Preferencereturnrepresentationandreturnminimal). +[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference. Services MUST return an error if the property is not updatable. @@ -929,8 +925,7 @@ Upon successful completion the service responds with either [`200 OK`](#ResponseCode200OK) and a representation of the updated collection, or [`204 No Content`](#ResponseCode204NoContent). The client may request that the response SHOULD include a body by specifying a -[Prefer](#Preferencereturnrepresentationandreturnminimal) header with a value of -[`return=representation`](#Preferencereturnrepresentationandreturnminimal). +[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference. Services MUST return an error if the property is not updatable.