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:
      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

            People

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

              Dates

              • Created:
                Updated:
                Resolved: