Skip to content

Commit

Permalink
Heiko's suggestions
Browse files Browse the repository at this point in the history
  • Loading branch information
@ralfhandl
ralfhandl committed Nov 9, 2023
1 parent fcf4a4b commit 6371a7e
Show file tree
Hide file tree
Showing 3 changed files with 15 additions and 25 deletions.
10 changes: 5 additions & 5 deletions docs/odata-protocol/odata-protocol.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1805,7 +1805,7 @@ <h3 id="1143-update-an-entity"><a name="UpdateanEntity" href="#UpdateanEntity">1
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>Upon successful completion the service responds with either <a href="#ResponseCode200OK"><code>200 OK</code></a> and a representation of the updated entity, or <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>. The client may request that the response SHOULD include a body by specifying a <a href="#Preferencereturnrepresentationandreturnminimal"><code>Prefer</code></a> header with a value of <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=representation</code></a>, or by specifying the system query options <a href="#SystemQueryOptionselect"><code>$select</code></a> or <a href="#SystemQueryOptionexpand"><code>$expand</code></a>. If the service uses ETags for optimistic concurrency control, the entities in the response MUST include ETags.</p>
<p>Upon successful completion the service responds with either <a href="#ResponseCode200OK"><code>200 OK</code></a> and a representation of the updated entity, or <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>. The client may request that the response SHOULD include a body by specifying a <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=representation</code></a> preference, or by specifying the system query options <a href="#SystemQueryOptionselect"><code>$select</code></a> or <a href="#SystemQueryOptionexpand"><code>$expand</code></a>. If the service uses ETags for optimistic concurrency control, the entities in the response MUST include ETags.</p>
<h4 id="11431-update-related-entities-when-updating-an-entity"><a name="UpdateRelatedEntitiesWhenUpdatinganEntity" href="#UpdateRelatedEntitiesWhenUpdatinganEntity">11.4.3.1 Update Related Entities When Updating an Entity</a></h4>
<p>Update requests with an OData-Version header with a value of <code>4.0</code> 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.</p>
<p>Payloads with an <code>OData-Version</code> header with a value of <code>4.01</code> or greater MAY include nested entities and entity references that specify the full set of to be related entities, or a nested <a href="#DeltaPayloads">delta payload</a> 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.</p>
Expand Down Expand Up @@ -1913,7 +1913,7 @@ <h3 id="1147-managing-media-entities"><a name="ManagingMediaEntities" href="#Man
<h4 id="11471-create-a-media-entity"><a name="CreateaMediaEntity" href="#CreateaMediaEntity">11.4.7.1 Create a Media Entity</a></h4>
<p>A <code>POST</code> 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 <a href="#HeaderContentType"><code>Content-Type</code></a> 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.</p>
<p>Upon successful completion, the response MUST contain <a href="#HeaderLocation"><code>Location</code></a> header that contains the edit URL of the created media entity.</p>
<p>Upon successful completion the service responds with either <a href="#ResponseCode201Created"><code>201 Created</code></a>, or <a href="#ResponseCode204NoContent"><code>204 No Content</code></a> if the request included a <a href="#Preferencereturnrepresentationandreturnminimal"><code>Prefer</code></a> header with a value of <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=minimal</code></a>.</p>
<p>Upon successful completion the service responds with either <a href="#ResponseCode201Created"><code>201 Created</code></a>, or <a href="#ResponseCode204NoContent"><code>204 No Content</code></a> if the request included a <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=minimal</code></a> preference.</p>
<h4 id="11472-update-a-media-entity-stream"><a name="UpdateaMediaEntityStream" href="#UpdateaMediaEntityStream">11.4.7.2 Update a Media Entity Stream</a></h4>
<p>A successful <code>PUT</code> request to the media edit URL of a media entity changes the media stream of the entity.</p>
<p>If the entity includes an ETag value for the media stream, the client MUST include an <a href="#HeaderIfMatch"><code>If-Match</code></a> header with the ETag value.</p>
Expand Down Expand Up @@ -1966,7 +1966,7 @@ <h4 id="11491-update-a-primitive-property"><a name="UpdateaPrimitiveProperty" hr
<p>A successful <code>PUT</code> 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.</p>
<p>A successful <code>PUT</code> request to the edit URL for the <a href="#RequestingaPropertysRawValueusingvalue">raw value</a> 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.</p>
<p>The same rules apply whether this is a regular property or a dynamic property.</p>
<p>Upon successful completion the service responds with either <a href="#ResponseCode200OK"><code>200 OK</code></a> or <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>. The client may request that the response SHOULD include a body by specifying a <a href="#Preferencereturnrepresentationandreturnminimal">Prefer</a> header with a value of <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=representation</code></a>.</p>
<p>Upon successful completion the service responds with either <a href="#ResponseCode200OK"><code>200 OK</code></a> or <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>. The client may request that the response SHOULD include a body by specifying a <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=representation</code></a> preference.</p>
<p>Services MUST return an error if the property is not updatable.</p>
<h4 id="11492-set-a-value-to-null"><a name="SetaValuetoNull" href="#SetaValuetoNull">11.4.9.2 Set a Value to Null</a></h4>
<p>A successful <code>DELETE</code> request to the edit URL for a structural property, or to the edit URL of the <a href="#RequestingaPropertysRawValueusingvalue">raw value</a> of a primitive property, sets the property to null. The request body is ignored and should be empty.</p>
Expand All @@ -1980,15 +1980,15 @@ <h4 id="11493-update-a-complex-property"><a name="UpdateaComplexProperty" href="
<p>The service MUST directly modify only those properties of the complex type specified in the payload of the <code>PATCH</code> request.</p>
<p>If a complex-typed property is set to a different type in a <code>PATCH</code> request, properties shared through inheritance, as well as dynamic properties, are retained (unless overwritten by new values in the payload). Other properties of the original type are discarded.</p>
<p>The service MAY additionally support clients sending a <code>PUT</code> request to a URL that specifies a complex type. In this case, the service MUST replace the entire complex property with the values specified in the request body and set all unspecified properties to their default value.</p>
<p>Upon successful completion the service responds with either <a href="#ResponseCode200OK"><code>200 OK</code></a> or <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>. The client may request that the response SHOULD include a body by specifying a <a href="#Preferencereturnrepresentationandreturnminimal">Prefer</a> header with a value of <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=representation</code></a>.</p>
<p>Upon successful completion the service responds with either <a href="#ResponseCode200OK"><code>200 OK</code></a> or <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>. The client may request that the response SHOULD include a body by specifying a <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=representation</code></a> preference.</p>
<p>Services MUST return an error if the property is not updatable.</p>
<h4 id="11494-update-a-collection-property"><a name="UpdateaCollectionProperty" href="#UpdateaCollectionProperty">11.4.9.4 Update a Collection Property</a></h4>
<p>A successful <code>PUT</code> 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.</p>
<p>The service MUST replace the entire value with the value supplied in the request body.</p>
<p>A successful <code>POST</code> 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 <a href="#RequestinganIndividualMemberofanOrderedCollection"><code>$index</code></a> MAY be used to specify the insert position.</p>
<p>A successful <code>DELETE</code> request to the edit URL of a collection property deletes all items in that collection.</p>
<p>Since collection members have no individual identity, <code>PATCH</code> is not supported for collection properties.</p>
<p>Upon successful completion the service responds with either <a href="#ResponseCode200OK"><code>200 OK</code></a> and a representation of the updated collection, or <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>. The client may request that the response SHOULD include a body by specifying a <a href="#Preferencereturnrepresentationandreturnminimal">Prefer</a> header with a value of <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=representation</code></a>.</p>
<p>Upon successful completion the service responds with either <a href="#ResponseCode200OK"><code>200 OK</code></a> and a representation of the updated collection, or <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>. The client may request that the response SHOULD include a body by specifying a <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=representation</code></a> preference.</p>
<p>Services MUST return an error if the property is not updatable.</p>
<h3 id="11410-managing-members-of-an-ordered-collection"><a name="ManagingMembersofanOrderedCollection" href="#ManagingMembersofanOrderedCollection">11.4.10 Managing Members of an Ordered Collection</a></h3>
<p>Collections annotated with the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#Ordered"><code>Core.Ordered</code></a> term (see <a href="#ODataVocCore">OData-VocCore</a>) 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.</p>
Expand Down
15 changes: 5 additions & 10 deletions docs/odata-protocol/odata-protocol.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.

#### <a name="UpdateaMediaEntityStream" href="#UpdateaMediaEntityStream">11.4.7.2 Update a Media Entity Stream</a>

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down
15 changes: 5 additions & 10 deletions odata-protocol/11.4 Data Modification.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down

0 comments on commit 6371a7e

Please sign in to comment.