Uploaded image for project: 'OASIS Open Data Protocol (OData) TC'
  1. OASIS Open Data Protocol (OData) TC
  2. ODATA-1398

Improve text and examples for JSON and multipart batch

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.01_OS
    • Fix Version/s: V4.01_ERRATA01
    • Component/s: JSON Format, Protocol
    • Labels:
      None
    • Proposal:
      Hide

      Feedback from Martin Zurmuehl:

      1. https://docs.oasis-open.org/odata/odata-json-format/v4.01/cos01/odata-json-format-v4.01-cos01.html#sec_BatchResponse

      Example 50 only shows the body, the other response elements are missing, example 51 is more complete, as is the corresponding example 104 here: https://docs.oasis-open.org/odata/odata/v4.01/cs02/part1-protocol/odata-v4.01-cs02-part1-protocol.html#sec_MultipartBatchResponse).

      Extend it to 

      HTTP/1.1 200 Ok
      OData-Version: 4.01
      Content-Length: ####
      Content-Type: application/json
      
      ...here goes the current example...

       

      2. The normative text doesn't state which HTTP response code to send for synchronous batch responses; for async responses (19.6.) it is explicitly stated. Part 1: Protocol states this explicitly in https://docs.oasis-open.org/odata/odata/v4.01/cs02/part1-protocol/odata-v4.01-cs02-part1-protocol.html#sec_BatchRequestHeaders.

      However this is (mis)placed under „Batch Request Headers“: move it up to 11.7 Batch Request because it is valid for all response formats.

      3. The statement „but the processing is yet to be completed“ suggests that processing is not finished when sending 200 OK. We should remove this and explicitly state that the request can also be streamed.

      Text for 2. and 3. in 11.7 Batch Request

      If the set of request headers of a batch request are valid the service MUST return a 200 OK 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 be processed as soon as they are receivedmay subsequently fail or be malformed; however, this enables clients to stream batch requests, and batch implementations to stream the results. 

      If the service receives a batch request with an invalid set of headers it MUST return a 4xx response code and perform no further processing of the batch request.

       

       

      Show
      Feedback from Martin Zurmuehl: 1.  https://docs.oasis-open.org/odata/odata-json-format/v4.01/cos01/odata-json-format-v4.01-cos01.html#sec_BatchResponse Example 50 only shows the body, the other response elements are missing, example 51 is more complete, as is the corresponding example 104 here:  https://docs.oasis-open.org/odata/odata/v4.01/cs02/part1-protocol/odata-v4.01-cs02-part1-protocol.html#sec_MultipartBatchResponse ). Extend it to  HTTP/1.1 200 Ok OData-Version: 4.01 Content-Length: #### Content-Type: application/json ...here goes the current example...   2. The normative text doesn't state which HTTP response code to send for synchronous batch responses; for async responses (19.6.) it is explicitly stated. Part 1: Protocol states this explicitly in  https://docs.oasis-open.org/odata/odata/v4.01/cs02/part1-protocol/odata-v4.01-cs02-part1-protocol.html#sec_BatchRequestHeaders. However this is (mis)placed under „Batch Request Headers“: move it up to 11.7 Batch Request because it is valid for all response formats. 3. The statement „but the processing is yet to be completed“ suggests that processing is not finished when sending 200 OK. We should remove this and explicitly state that the request can also be streamed. Text for 2. and 3. in 11.7 Batch Request If the set of request headers of a batch request are valid the service MUST return a  200 OK  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 be processed as soon as they are received may subsequently fail or be malformed; however , this enables clients to stream batch requests, and batch implementations to stream the results.  If the service receives a batch request with an invalid set of headers it MUST return a  4xx response code  and perform no further processing of the batch request.    
    • Resolution:
      Show
      https://github.com/oasis-tcs/odata-specs/pull/195

      Attachments

        Activity

          People

          • Assignee:
            handl Ralf Handl
            Reporter:
            handl Ralf Handl
          • Watchers:
            1 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: