OASIS Open Data Protocol (OData) TCIcon indicating the project type

OASIS Open Data Protocol (OData) TC

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

consider replacing SchemaVersion header with $SchemaVersion query option, or root URL versioning

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.01_WD01
    • Fix Version/s: V4.01_CSD02
    • Component/s: Protocol
    • Labels:
      None
    • Environment:

      Applied

    • Proposal:
      Hide

      If the only difference between two request is the SchemaVersion Header value, the response is not cachable in all today-browser-implementations (the 'vary' header is not treated correct).
      --> To enable caching of responses we need differentiating URL's. We should use a $SchemaVersion query option. It is superior to adding a segment to the root url, because clients are anyhow familiar with adding query options.
      The usage of a $SchemaVersion query option in the relative contextURLs is save; according to rfc3986 query options on the base URI are not kept during reference resolution for all relevant cases.
      Depending on the value of the SchemaVersion it may be necessary to percent-encode it before the URI is formed.

      Revised proposal:
      Remove SchemaVersion header in place of a $SchemaVersion query option.
      Limit characters in SchemaVersion to things that don't have to be percent encoded:
      Character set: unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"

      Show
      If the only difference between two request is the SchemaVersion Header value, the response is not cachable in all today-browser-implementations (the 'vary' header is not treated correct). --> To enable caching of responses we need differentiating URL's. We should use a $SchemaVersion query option. It is superior to adding a segment to the root url, because clients are anyhow familiar with adding query options. The usage of a $SchemaVersion query option in the relative contextURLs is save; according to rfc3986 query options on the base URI are not kept during reference resolution for all relevant cases. Depending on the value of the SchemaVersion it may be necessary to percent-encode it before the URI is formed. Revised proposal: Remove SchemaVersion header in place of a $SchemaVersion query option. Limit characters in SchemaVersion to things that don't have to be percent encoded: Character set: unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
    • Resolution:
      Hide

      https://www.oasis-open.org/committees/download.php/60366/odata-v4.01-wd02-part1-protocol-2017-03-24.docx

      Show
      https://www.oasis-open.org/committees/download.php/60366/odata-v4.01-wd02-part1-protocol-2017-03-24.docx

      Description

      In OData-980 we clarified how odata.type is annotated, but this brought up the question as to whether we should be using a SchemaVersion request header or a $SchemaVersion query option to request a particular version of data. A queryoption (or root url versioning) has the advantage of making the response cacheable, we just need to make sure composition rules are well thought-out (i.e., for using contexturl as base for relative references)

        Attachments

          Activity

          Ascending order - Click to sort in descending order
          Hide
          Permalink
          evan.ireland.2 Evan Ireland added a comment -

          A query option might not be applicable to PATCH/POST/PUT requests.

          But if we want the server to be able to reject requests where the client is using an incompatible schema version, then a solution based only on URL syntax probably isn't viable.

          The "root URL versioning" approach could be a workable alternative though.

          Show
          evan.ireland.2 Evan Ireland added a comment - A query option might not be applicable to PATCH/POST/PUT requests. But if we want the server to be able to reject requests where the client is using an incompatible schema version, then a solution based only on URL syntax probably isn't viable. The "root URL versioning" approach could be a workable alternative though.
          Hide
          Permalink
          martinzurmuehl Martin Zurmuehl added a comment -

          Query option are applicable to all type of requests (including PATCH/POST/PUT requests)

          Show
          martinzurmuehl Martin Zurmuehl added a comment - Query option are applicable to all type of requests (including PATCH/POST/PUT requests)
          Hide
          Permalink
          mikep Michael Pizzo (Inactive) added a comment -

          Resolved as proposed 2017-3-16

          Show
          mikep Michael Pizzo (Inactive) added a comment - Resolved as proposed 2017-3-16
          Hide
          Permalink
          mikep Michael Pizzo (Inactive) added a comment -

          Application approved 2017-6-8.

          Show
          mikep Michael Pizzo (Inactive) added a comment - Application approved 2017-6-8.

            People

            • Assignee:
              martinzurmuehl Martin Zurmuehl
              Reporter:
              handl Ralf Handl
            • Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: