Skip to content

Commit

Permalink
ODATA-1609 (#212)
Browse files Browse the repository at this point in the history 
https://issues.oasis-open.org/browse/ODATA-1609
  • Loading branch information
@HeikoTheissen
HeikoTheissen authored Nov 22, 2023
1 parent 5b1a1c0 commit 48a734e
Show file tree
Hide file tree
Showing 5 changed files with 54 additions and 33 deletions.
29 changes: 20 additions & 9 deletions docs/odata-protocol/odata-protocol.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -483,10 +483,22 @@ <h1 id="1-introduction"><a name="Introduction" href="#Introduction">1 Introducti
<p>The <a href="#ODataCSDL">OData-CSDLXML</a> specification defines an XML representation of the entity data model exposed by an OData service.</p>
<p>The <a href="#ODataJSON">OData-JSON</a> document specifies the JSON format of the resource representations that are exchanged using OData.</p>
<h2 id="11-changes-from-earlier-versions"><a name="ChangesfromEarlierVersions" href="#ChangesfromEarlierVersions">1.1 Changes from Earlier Versions</a></h2>
<!-- TODO -->

<!-- Describe significant changes from previous differently-numbered Versions, not changes between stages of the current Version -->

<table>
<thead>
<tr class="header">
<th>Section</th>
<th>Feature / Change</th>
<th>Issue</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><a href="#DataModification">Section 11.4</a></td>
<td>Response code <code>204 No Content</code> after successful data modification if requested response could not be constructed</td>
<td><a href="https://issues.oasis-open.org/browse/ODATA-1609">ODATA-1609</a></td>
</tr>
</tbody>
</table>
<h2 id="12-glossary"><a name="Glossary" href="#Glossary">1.2 Glossary</a></h2>
<h3 id="121-definitions-of-terms"><a name="DefinitionsofTerms" href="#DefinitionsofTerms">1.2.1 Definitions of Terms</a></h3>
<h3 id="122-acronyms-and-abbreviations"><a name="AcronymsandAbbreviations" href="#AcronymsandAbbreviations">1.2.2 Acronyms and Abbreviations</a></h3>
Expand Down Expand Up @@ -886,7 +898,7 @@ <h3 id="913-response-code-202-accepted"><a name="ResponseCode202Accepted" href="
<p><code>202 Accepted</code> indicates that the <a href="#DataServiceRequests">Data Service Request</a> has been accepted and has not yet completed executing asynchronously. The asynchronous handling of requests is defined in the sections on <a href="#AsynchronousRequests">Asynchronous Requests</a> and <a href="#AsynchronousBatchRequests">Asynchronous Batch Requests</a>.</p>
<h3 id="914-response-code-204-no-content"><a name="ResponseCode204NoContent" href="#ResponseCode204NoContent">9.1.4 Response Code <code>204 No Content</code></a></h3>
<p>A request returns <code>204 No Content</code> if the requested resource has the <code>null</code> value, or if the service applies a <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=minimal</code></a> preference. In this case, the response body MUST be empty.</p>
<p>As defined in <a href="#rfc7231">RFC7231</a>, a <a href="#DataModification">Data Modification Request</a> that responds with <code>204 No Content</code> MAY include an <code>ETag</code> header with a value reflecting the result of the data modification if and only if the client can reasonably “know” the new representation of the resource without actually receiving it. For a <code>PUT</code> request this means that the response body of a corresponding <code>200 OK</code> or <code>201 Created</code> response would have been identical to the request body, i.e. no server-side modification of values sent in the request body, no server-calculated values etc. For a <code>PATCH</code> request this means that the response body of a corresponding <code>200 OK</code> or <code>201 Created</code> response would have consisted of all values sent in the request body, plus (for values not sent in the request body) server-side values corresponding to the <code>ETag</code> value sent in the <code>If-Match</code> header of the <code>PATCH</code> request, i.e. the previous values “known” to the client.</p>
<p>As defined in <a href="#rfc7231">RFC7231</a>, a <a href="#DataModification">Data Modification Request</a> that responds with <code>204 No Content</code> MAY include an <a href="#HeaderETag"><code>ETag</code></a> header with a value reflecting the result of the data modification if and only if the client can reasonably “know” the new representation of the resource without actually receiving it. For a <code>PUT</code> request this means that the response body of a corresponding <code>200 OK</code> or <code>201 Created</code> response would have been identical to the request body, i.e. no server-side modification of values sent in the request body, no server-calculated values etc. For a <code>PATCH</code> request this means that the response body of a corresponding <code>200 OK</code> or <code>201 Created</code> response would have consisted of all values sent in the request body, plus (for values not sent in the request body) server-side values corresponding to the <code>ETag</code> value sent in the <code>If-Match</code> header of the <code>PATCH</code> request, i.e. the previous values “known” to the client.</p>
<h3 id="915-response-code-3xx-redirection"><a name="ResponseCode3xxRedirection" href="#ResponseCode3xxRedirection">9.1.5 Response Code <code>3xx Redirection</code></a></h3>
<p>As per <a href="#rfc7231">RFC7231</a>, a <code>3xx Redirection</code> indicates that further action needs to be taken by the client in order to fulfill the request. In this case, the response SHOULD include a <a href="#HeaderLocation"><code>Location</code></a> header, as appropriate, with the URL from which the result can be obtained; it MAY include a <a href="#HeaderRetryAfter"><code>Retry-After</code></a> header.</p>
<h3 id="916-response-code-304-not-modified"><a name="ResponseCode304NotModified" href="#ResponseCode304NotModified">9.1.6 Response Code <code>304 Not Modified</code></a></h3>
Expand Down Expand Up @@ -1712,7 +1724,7 @@ <h3 id="1133-delta-payloads"><a name="DeltaPayloads" href="#DeltaPayloads">11.3.
<h2 id="114-data-modification"><a name="DataModification" href="#DataModification">11.4 Data Modification</a></h2>
<p>Updatable OData services support Create, Update, and Delete operations for some or all exposed entities. Additionally, <a href="#Actions">Actions</a> supported by a service can affect the state of the system.</p>
<p>A successfully completed <a href="#DataModification">Data Modification Request</a> must not violate the integrity of the data.</p>
<p>The client may request whether content be returned from a Create, Update, or Delete request, or the invocation of an Action, by specifying the <a href="#Preferencereturnrepresentationandreturnminimal"><code>return</code></a> preference.</p>
<p>The client may request whether content be returned from a Create, Update, or Delete request, or the invocation of an Action, by specifying the <a href="#Preferencereturnrepresentationandreturnminimal"><code>return</code></a> preference. A <a href="#SuccessResponses">success response</a> indicates that data have been modified, regardless of whether the requested content could be returned.</p>
<h3 id="1141-common-data-modification-semantics"><a name="CommonDataModificationSemantics" href="#CommonDataModificationSemantics">11.4.1 Common Data Modification Semantics</a></h3>
<p><a href="#DataModification">Data Modification Requests</a> share the following semantics.</p>
<h4 id="11411-use-of-etags-for-avoiding-update-conflicts"><a name="UseofETagsforAvoidingUpdateConflicts" href="#UseofETagsforAvoidingUpdateConflicts">11.4.1.1 Use of ETags for Avoiding Update Conflicts</a></h4>
Expand Down Expand Up @@ -1748,8 +1760,7 @@ <h3 id="1142-create-an-entity"><a name="CreateanEntity" href="#CreateanEntity">1
<p>If the entity being created is not an open entity, additional property values beyond those specified in the metadata SHOULD NOT be sent in the request body. The service MUST fail if unable to persist all property values specified in the request.</p>
<p>Properties computed by the service (annotated with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#Computed"><code>Core.Computed</code></a>, see <a href="#ODataVocCore">OData-VocCore</a>) and properties that are tied to properties of the principal entity by a referential constraint, can be omitted and MUST be ignored if included in the request.</p>
<p>Properties with a defined default value, nullable properties, and collection-valued properties omitted from the request are set to the default value, null, or an empty collection, respectively.</p>
<p>Upon successful completion, the response MUST contain a <a href="#HeaderLocation"><code>Location</code></a> header that contains the edit URL or read URL of the created entity.</p>
<p>Upon successful completion the service MUST respond with either <a href="#ResponseCode201Created"><code>201 Created</code></a> and a representation of the created entity, or <a href="#ResponseCode204NoContent"><code>204 No Content</code></a> if the request included a <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=minimal</code></a> preference and did not include the system query options <a href="#SystemQueryOptionselect"><code>$select</code></a> and <a href="#SystemQueryOptionexpand"><code>$expand</code></a>.</p>
<p>Upon successful creation of the entity, the service MUST respond with either <a href="#ResponseCode201Created"><code>201 Created</code></a> and a representation of the created entity, or <a href="#ResponseCode204NoContent"><code>204 No Content</code></a> if the request included a <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=minimal</code></a> preference and did not include the system query options <a href="#SystemQueryOptionselect"><code>$select</code></a> and <a href="#SystemQueryOptionexpand"><code>$expand</code></a>, or if a representation of the created entity could not be constructed. In either case, if the service is able to construct the edit URL or read URL of the created entity, the response MUST contain that URL in a <a href="#HeaderLocation"><code>Location</code></a> header.</p>
<h4 id="11421-link-to-related-entities-when-creating-an-entity"><a name="LinktoRelatedEntitiesWhenCreatinganEntity" href="#LinktoRelatedEntitiesWhenCreatinganEntity">11.4.2.1 Link to Related Entities When Creating an Entity</a></h4>
<p>To create a new entity with links to existing entities in a single request, the client includes references to the related entities in the request body.</p>
<p>The representation for referencing related entities is format-specific.</p>
Expand Down Expand Up @@ -1806,7 +1817,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>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>
<p>Upon successful completion of the update, 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. If a representation of the updated entity could not be constructed, the service MAY ignore the system query options and respond with <code>204 No Content</code>.</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
28 changes: 16 additions & 12 deletions docs/odata-protocol/odata-protocol.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -344,8 +344,9 @@ resource representations that are exchanged using OData.

## <a name="ChangesfromEarlierVersions" href="#ChangesfromEarlierVersions">1.1 Changes from Earlier Versions</a>

<!-- TODO -->
<!-- Describe significant changes from previous differently-numbered Versions, not changes between stages of the current Version -->
Section | Feature / Change | Issue
--------|------------------|------
[Section 11.4](#DataModification)| Response code `204 No Content` after successful data modification if requested response could not be constructed| [ODATA-1609](https://issues.oasis-open.org/browse/ODATA-1609)

## <a name="Glossary" href="#Glossary">1.2 Glossary</a>

Expand Down Expand Up @@ -1807,7 +1808,7 @@ In this case, the response body MUST be empty.

As defined in [RFC7231](#rfc7231), a [Data Modification
Request](#DataModification) that responds with
`204 No Content` MAY include an `ETag` header with a value reflecting
`204 No Content` MAY include an [`ETag`](#HeaderETag) header with a value reflecting
the result of the data modification if and only if the client can
reasonably "know" the new representation of the resource without
actually receiving it. For a `PUT` request this means that the response
Expand Down Expand Up @@ -3963,6 +3964,8 @@ must not violate the integrity of the data.
The client may request whether content be returned from a Create,
Update, or Delete request, or the invocation of an Action, by specifying
the [`return`](#Preferencereturnrepresentationandreturnminimal) preference.
A [success response](#SuccessResponses) indicates that data have been modified,
regardless of whether the requested content could be returned.

### <a name="CommonDataModificationSemantics" href="#CommonDataModificationSemantics">11.4.1 Common Data Modification Semantics</a>

Expand Down Expand Up @@ -4138,17 +4141,16 @@ Properties with a defined default value, nullable properties, and
collection-valued properties omitted from the request are set to the
default value, null, or an empty collection, respectively.

Upon successful completion, the response MUST contain a
[`Location`](#HeaderLocation) header that contains the edit URL or read URL of the
created entity.

Upon successful completion the service MUST respond with either
Upon successful creation of the entity, the service MUST respond with either
[`201 Created`](#ResponseCode201Created) and a representation of the
created entity, or [`204 No Content`](#ResponseCode204NoContent) if the
request included a
[`return=minimal`](#Preferencereturnrepresentationandreturnminimal) preference and did not
include the system query options [`$select`](#SystemQueryOptionselect)
and [`$expand`](#SystemQueryOptionexpand).
and [`$expand`](#SystemQueryOptionexpand), or if a representation of the created
entity could not be constructed. In either case, if the service is able to construct
the edit URL or read URL of the created entity, the response MUST contain that URL in a
[`Location`](#HeaderLocation) header.

#### <a name="LinktoRelatedEntitiesWhenCreatinganEntity" href="#LinktoRelatedEntitiesWhenCreatinganEntity">11.4.2.1 Link to Related Entities When Creating an Entity</a>

Expand Down Expand Up @@ -4342,16 +4344,18 @@ 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
Upon successful completion of the update, the service responds with either
[`200 OK`](#ResponseCode200OK) and a representation of the updated
entity, or [`204 No Content`](#ResponseCode204NoContent). The client may
entity, or [`204 No Content`](#ResponseCode204NoContent).
The client may
request that the response SHOULD include a body by specifying a
[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference, or by
specifying the system query options
[`$select`](#SystemQueryOptionselect) or
[`$expand`](#SystemQueryOptionexpand). If the service uses ETags for
optimistic concurrency control, the entities in the response MUST
include ETags.
include ETags. If a representation of the updated entity could not be constructed,
the service MAY ignore the system query options and respond with `204 No Content`.

#### <a name="UpdateRelatedEntitiesWhenUpdatinganEntity" href="#UpdateRelatedEntitiesWhenUpdatinganEntity">11.4.3.1 Update Related Entities When Updating an Entity</a>

Expand Down
7 changes: 5 additions & 2 deletions odata-protocol/1 Introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,11 @@ resource representations that are exchanged using OData.

## ##subsec Changes from Earlier Versions

<!-- TODO -->
<!-- Describe significant changes from previous differently-numbered Versions, not changes between stages of the current Version -->
Section | Feature / Change | Issue
--------|------------------|------
[Section ##DataModification]|
Response code `204 No Content` after successful data modification if requested response could not be constructed|
[ODATA-1609](https://issues.oasis-open.org/browse/ODATA-1609)

## ##subsec Glossary

Expand Down
Loading

0 comments on commit 48a734e

Please sign in to comment.