Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

ODATA-1398 #195

Merged
merged 3 commits into from
Nov 29, 2023
Merged

ODATA-1398 #195

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d7527d5
ODATA-1398
ralfhandl Oct 20, 2023
fe347b6
Apply suggestions from code review
ralfhandl Oct 23, 2023
426efdb
200 OK
ralfhandl Oct 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
55 changes: 30 additions & 25 deletions docs/odata-json-format/odata-json-format.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1670,32 +1670,37 @@ <h2 id="195-batch-response"><a name="BatchResponse" href="#BatchResponse">19.5 B
<p>Relative URLs in a response object follow the rules for <a href="#RelativeURLs">relative URLs</a> based on the request URL of the corresponding request. Especially: URLs in responses MUST NOT contain <code>$</code>-prefixed request identifiers.</p>
<div class="example">
<p>Example 51: referencing the batch request <a href="#batchRequest">example 48</a> above, assume all the requests except the final query request succeed. In this case the response would be</p>
<div class="sourceCode" id="cb55"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb55-1"><a href="#cb55-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb55-2"><a href="#cb55-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;responses&quot;</span><span class="fu">:</span> <span class="ot">[</span></span>
<span id="cb55-3"><a href="#cb55-3" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb55-4"><a href="#cb55-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;id&quot;</span><span class="fu">:</span> <span class="st">&quot;0&quot;</span><span class="fu">,</span></span>
<span id="cb55-5"><a href="#cb55-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;status&quot;</span><span class="fu">:</span> <span class="dv">200</span><span class="fu">,</span></span>
<span id="cb55-6"><a href="#cb55-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;body&quot;</span><span class="fu">:</span> <span class="er">&lt;JSON</span> <span class="er">representation</span> <span class="er">of</span> <span class="er">the</span> <span class="er">Customer</span> <span class="er">entity</span> <span class="er">with</span> <span class="er">key</span> <span class="er">ALFKI&gt;</span></span>
<span id="cb55-7"><a href="#cb55-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<div class="sourceCode" id="cb55"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb55-1"><a href="#cb55-1" aria-hidden="true" tabindex="-1"></a><span class="er">HTTP/1.1</span> <span class="er">200</span> <span class="er">OK</span></span>
<span id="cb55-2"><a href="#cb55-2" aria-hidden="true" tabindex="-1"></a><span class="er">OData-Version:</span> <span class="er">4.01</span></span>
<span id="cb55-3"><a href="#cb55-3" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Length:</span> <span class="er">####</span></span>
<span id="cb55-4"><a href="#cb55-4" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
<span id="cb55-5"><a href="#cb55-5" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb55-6"><a href="#cb55-6" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb55-7"><a href="#cb55-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;responses&quot;</span><span class="fu">:</span> <span class="ot">[</span></span>
<span id="cb55-8"><a href="#cb55-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb55-9"><a href="#cb55-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;id&quot;</span><span class="fu">:</span> <span class="st">&quot;1&quot;</span><span class="fu">,</span></span>
<span id="cb55-10"><a href="#cb55-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;status&quot;</span><span class="fu">:</span> <span class="dv">204</span></span>
<span id="cb55-11"><a href="#cb55-11" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb55-12"><a href="#cb55-12" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb55-13"><a href="#cb55-13" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;id&quot;</span><span class="fu">:</span> <span class="st">&quot;2&quot;</span><span class="fu">,</span></span>
<span id="cb55-14"><a href="#cb55-14" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;status&quot;</span><span class="fu">:</span> <span class="dv">201</span><span class="fu">,</span></span>
<span id="cb55-15"><a href="#cb55-15" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;headers&quot;</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb55-16"><a href="#cb55-16" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;location&quot;</span><span class="fu">:</span> <span class="st">&quot;http://host/service.svc/Customer(&#39;POIUY&#39;)&quot;</span></span>
<span id="cb55-17"><a href="#cb55-17" aria-hidden="true" tabindex="-1"></a> <span class="fu">},</span></span>
<span id="cb55-18"><a href="#cb55-18" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;body&quot;</span><span class="fu">:</span> <span class="er">&lt;JSON</span> <span class="er">representation</span> <span class="er">of</span> <span class="er">the</span> <span class="er">new</span> <span class="er">Customer</span> <span class="er">entity&gt;</span></span>
<span id="cb55-19"><a href="#cb55-19" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb55-20"><a href="#cb55-20" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb55-21"><a href="#cb55-21" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;id&quot;</span><span class="fu">:</span> <span class="st">&quot;3&quot;</span><span class="fu">,</span></span>
<span id="cb55-22"><a href="#cb55-22" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;status&quot;</span><span class="fu">:</span> <span class="dv">404</span><span class="fu">,</span></span>
<span id="cb55-23"><a href="#cb55-23" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;body&quot;</span><span class="fu">:</span> <span class="er">&lt;Error</span> <span class="er">message&gt;</span></span>
<span id="cb55-24"><a href="#cb55-24" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
<span id="cb55-25"><a href="#cb55-25" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
<span id="cb55-26"><a href="#cb55-26" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
<span id="cb55-9"><a href="#cb55-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;id&quot;</span><span class="fu">:</span> <span class="st">&quot;0&quot;</span><span class="fu">,</span></span>
<span id="cb55-10"><a href="#cb55-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;status&quot;</span><span class="fu">:</span> <span class="dv">200</span><span class="fu">,</span></span>
<span id="cb55-11"><a href="#cb55-11" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;body&quot;</span><span class="fu">:</span> <span class="er">&lt;JSON</span> <span class="er">representation</span> <span class="er">of</span> <span class="er">the</span> <span class="er">Customer</span> <span class="er">entity</span> <span class="er">with</span> <span class="er">key</span> <span class="er">ALFKI&gt;</span></span>
<span id="cb55-12"><a href="#cb55-12" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb55-13"><a href="#cb55-13" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb55-14"><a href="#cb55-14" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;id&quot;</span><span class="fu">:</span> <span class="st">&quot;1&quot;</span><span class="fu">,</span></span>
<span id="cb55-15"><a href="#cb55-15" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;status&quot;</span><span class="fu">:</span> <span class="dv">204</span></span>
<span id="cb55-16"><a href="#cb55-16" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb55-17"><a href="#cb55-17" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb55-18"><a href="#cb55-18" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;id&quot;</span><span class="fu">:</span> <span class="st">&quot;2&quot;</span><span class="fu">,</span></span>
<span id="cb55-19"><a href="#cb55-19" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;status&quot;</span><span class="fu">:</span> <span class="dv">201</span><span class="fu">,</span></span>
<span id="cb55-20"><a href="#cb55-20" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;headers&quot;</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb55-21"><a href="#cb55-21" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;location&quot;</span><span class="fu">:</span> <span class="st">&quot;http://host/service.svc/Customer(&#39;POIUY&#39;)&quot;</span></span>
<span id="cb55-22"><a href="#cb55-22" aria-hidden="true" tabindex="-1"></a> <span class="fu">},</span></span>
<span id="cb55-23"><a href="#cb55-23" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;body&quot;</span><span class="fu">:</span> <span class="er">&lt;JSON</span> <span class="er">representation</span> <span class="er">of</span> <span class="er">the</span> <span class="er">new</span> <span class="er">Customer</span> <span class="er">entity&gt;</span></span>
<span id="cb55-24"><a href="#cb55-24" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb55-25"><a href="#cb55-25" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb55-26"><a href="#cb55-26" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;id&quot;</span><span class="fu">:</span> <span class="st">&quot;3&quot;</span><span class="fu">,</span></span>
<span id="cb55-27"><a href="#cb55-27" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;status&quot;</span><span class="fu">:</span> <span class="dv">404</span><span class="fu">,</span></span>
<span id="cb55-28"><a href="#cb55-28" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;body&quot;</span><span class="fu">:</span> <span class="er">&lt;Error</span> <span class="er">message&gt;</span></span>
<span id="cb55-29"><a href="#cb55-29" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
<span id="cb55-30"><a href="#cb55-30" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
<span id="cb55-31"><a href="#cb55-31" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<h2 id="196-asynchronous-batch-requests"><a name="AsynchronousBatchRequests" href="#AsynchronousBatchRequests">19.6 Asynchronous Batch Requests</a></h2>
<p>A batch request that specifies the <code>respond-async</code> preference MAY be executed asynchronously. This means that the "outer" batch request is executed asynchronously; this preference does not automatically cascade down to the individual requests within the batch. After successful execution of the batch request the response to the batch request is returned in the body of a response to an interrogation request against the status monitor resource URL, see section "Asynchronous Requests" in <a href="#ODataProtocol">OData-Protocol</a>.</p>
Expand Down
5 changes: 5 additions & 0 deletions docs/odata-json-format/odata-json-format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3189,6 +3189,11 @@ Example 51: referencing the batch request [example 48](#batchRequest) above, ass
the requests except the final query request succeed. In this case the
response would be
```json
HTTP/1.1 200 OK
OData-Version: 4.01
Content-Length: ####
Content-Type: application/json

{
"responses": [
{
Expand Down
16 changes: 8 additions & 8 deletions docs/odata-protocol/odata-protocol.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2210,6 +2210,8 @@ <h2 id="117-batch-requests"><a name="BatchRequests" href="#BatchRequests">11.7 B
<p>Batch requests are submitted as a single HTTP <code>POST</code> request to the batch endpoint of a service, located at the URL <code>$batch</code> relative to the service root.</p>
<p>Individual requests within a batch request are evaluated according to the same semantics used when the request appears outside the context of a batch request.</p>
<p>A batch request is represented using either the <a href="#MultipartBatchFormat">multipart batch format</a> defined in this document or the JSON batch format defined in <a href="#ODataJSON">OData-JSON</a>.</p>
<p>If the set of request headers of a batch request are valid the service MUST return a <a href="#ResponseCode200OK"><code>200 OK</code></a> HTTP response code to indicate that the batch request was accepted for processing, even if the processing is yet to be completed. The individual requests within the body of the batch request may be processed as soon as they are received, this enables clients to stream batch requests, and batch implementations to stream the results.</p>
<p>If the service receives a batch request with an invalid set of headers it MUST return a <a href="#ClientErrorResponses"><code>4xx response code</code></a> and perform no further processing of the batch request.</p>
<h3 id="1171-batch-request-headers"><a name="BatchRequestHeaders" href="#BatchRequestHeaders">11.7.1 Batch Request Headers</a></h3>
<p>A batch request using the <a href="#MultipartBatchFormat">multipart batch format</a> MUST contain a <a href="#HeaderContentType"><code>Content-Type</code></a> header specifying a content type of <code>multipart/mixed</code> and a <code>boundary</code> parameter as defined in <a href="#rfc2046">RFC2046</a>.</p>
<div class="example">
Expand All @@ -2233,8 +2235,6 @@ <h3 id="1171-batch-request-headers"><a name="BatchRequestHeaders" href="#BatchRe
</div>
<p>Batch requests SHOULD contain the applicable <code>OData-Version</code> header.</p>
<p>Batch requests SHOULD contain an <a href="#HeaderAccept"><code>Accept</code></a> header specifying the desired batch response format, either <code>multipart/mixed</code> or <code>application/json</code>. If no <code>Accept</code> header is provided, services SHOULD respond with the content type of the request.</p>
<p>If the set of request headers of a batch request are valid the service MUST return a <a href="#ResponseCode200OK"><code>200 OK</code></a> HTTP response code to indicate that the batch request was accepted for processing, but the processing is yet to be completed. The individual requests within the body of the batch request may subsequently fail or be malformed; however, this enables batch implementations to stream the results.</p>
<p>If the service receives a batch request with an invalid set of headers it MUST return a <a href="#ClientErrorResponses"><code>4xx response code</code></a> and perform no further processing of the batch request.</p>
<h3 id="1172-request-dependencies"><a name="RequestDependencies" href="#RequestDependencies">11.7.2 Request Dependencies</a></h3>
<p>Requests within a batch may have dependencies on other requests according to the particular batch format.</p>
<p>In the JSON format, requests may explicitly declare a dependency on other requests that must be successfully processed before the current request. In addition, requests may be specified as part of an <em>atomicity group</em> whose members MUST either all succeed, or all fail. If a request fails, then any dependent requests within the JSON format return <a href="#ResponseCode424FailedDependency"><code>424 Failed Dependency</code></a>.</p>
Expand Down Expand Up @@ -2443,15 +2443,15 @@ <h4 id="11775-multipart-batch-response"><a name="MultipartBatchResponse" href="#
<p>A response to an operation in a batch MUST be formatted exactly as it would have appeared outside of a batch as described in the corresponding subsections of chapter <a href="#DataServiceRequests">Data Service Requests</a>. Relative URLs in each individual response are relative to the request URL of the corresponding individual request. URLs in responses MUST NOT contain <code>$</code>-prefixed request identifiers.</p>
<div class="example">
<p>Example 107: referencing the batch request example 101 above, assume all the requests except the final query request succeed. In this case the response would be</p>
<pre><code>HTTP/1.1 200 Ok
<pre><code>HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: ####
Content-Type: multipart/mixed; boundary=b_243234_25424_ef_892u748

--b_243234_25424_ef_892u748
Content-Type: application/http

HTTP/1.1 200 Ok
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ###

Expand Down Expand Up @@ -2501,18 +2501,18 @@ <h4 id="11776-asynchronous-batch-requests"><a name="AsynchronousBatchRequests" h
</code></pre>
</div>
<p>When interrogating the monitor URL only the first request in the batch has finished processing and all the remaining requests are still being processed. Note that the actual multipart batch response itself is contained in an <code>application/http</code> wrapper as it is a response to a status monitor resource:</p>
<pre><code>HTTP/1.1 200 Ok
<pre><code>HTTP/1.1 200 OK
Content-Type: application/http

HTTP/1.1 200 Ok
HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: ####
Content-Type: multipart/mixed; boundary=b_243234_25424_ef_892u748

--b_243234_25424_ef_892u748
Content-Type: application/http

HTTP/1.1 200 Ok
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ###

Expand All @@ -2527,7 +2527,7 @@ <h4 id="11776-asynchronous-batch-requests"><a name="AsynchronousBatchRequests" h

--b_243234_25424_ef_892u748--</code></pre>
<p>After some time the client makes a second request using the returned monitor URL, not explicitly accepting <code>application/http</code>. The batch is completely processed and the response is the final result.</p>
<pre><code>HTTP/1.1 200 Ok
<pre><code>HTTP/1.1 200 OK
AsyncResult: 200
OData-Version: 4.0
Content-Length: ####
Expand Down