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

Rephrasing of section Delta Links in ODQP proposal page 1/2

    Details

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

      [Closed]

      Description

      Inside the current revision of the proposal for an OData Delta Query Protocol i.e. [OData Delta Query Protocol Design 2012-12-19.docx](https://www.oasis-open.org/committees/download.php/47755/OData%20Delta%20Query%20Protocol%20Design%202012-12-19.docx) please consider rewriting:
      """
      Delta Links

      An OData Service supports result maintenance by including a "delta link" url in the last page of results returned from a request for which the service can enumerate changes. This delta link is generated in place of the next link on the last page of the result. It is illegal for a response to contain both a delta link and a next page link.

      Clients can use this delta link to query the service for changes that have occurred to the result since the initial request.

      Delta links are returned only on requests that return a collection of zero or more entities. Requests for individual entities (for example ~/Customers('ALFKI') or property values (for example, ~/Customers('ALFKI')/ContactName) do not include delta links."""

      into:
      """
      Delta Links

      For any request for which the OData Service can enumerate changes the service SHOULD support result maintenance by including a "delta link" url in place of the next link on the last page of results returned.
      A response MAY contain a next page or a delta link, but MUST NOT contain both.

      Clients can use this delta link to query the service for changes that have occurred to the result since the initial request.

      Delta links MUST only be returned upon requests whose responses contain a collection of zero or more entities. Requests for individual entities or property values MUST NOT include delta links. Corresponding examples for such requests are ~/Customers('ALFKI') and ~/Customers('ALFKI')/ContactName respectively."""

      to ease understanding of main statements and extraction of conformance tests.

        Attachments

          Activity

          Ascending order - Click to sort in descending order
          Hide
          Permalink
          mikep Michael Pizzo (Inactive) added a comment -

          Applied slightly edited version:

          For any request for which the OData Service can enumerate changes the service SHOULD support result maintenance*, if requested,* by including a "delta link" url in place of the next link on the last page of results returned.

          A response MAY contain a next page link, a delta link, or neither, but MUST NOT contain both.

          Clients can use this delta link to query the service for changes that have occurred to the result since the initial request.

          Delta links MUST only be returned upon requests whose responses contain a collection of zero or more entities. Requests for individual entities or property values MUST NOT include delta links. Corresponding examples for such requests are ~/Customers('ALFKI') and ~/Customers('ALFKI')/ContactName respectively.

          Show
          mikep Michael Pizzo (Inactive) added a comment - Applied slightly edited version: For any request for which the OData Service can enumerate changes the service SHOULD support result maintenance*, if requested,* by including a "delta link" url in place of the next link on the last page of results returned. A response MAY contain a next page link, a delta link, or neither, but MUST NOT contain both. Clients can use this delta link to query the service for changes that have occurred to the result since the initial request. Delta links MUST only be returned upon requests whose responses contain a collection of zero or more entities. Requests for individual entities or property values MUST NOT include delta links. Corresponding examples for such requests are ~/Customers('ALFKI') and ~/Customers('ALFKI')/ContactName respectively.
          Hide
          Permalink
          sdrees Stefan Drees (Inactive) added a comment - - edited

          Thanks a lot Mike, for already implementing the slightly edited version. The change you made (to the proposed wording), does help me better understand the described service. Another place that contributed as a source of the misinterpretation.

          Please inspect also (esp. the last sentence!):

          """
          Requesting Delta Links

          An OData client may request that a service return delta links by including a Preference value of odata- request-deltas in the Prefer Header of the request. Services that support deltas should return a delta link, if possible for the request, but may ignore this value. Services may return delta links when this value has not been specified.
          """

          So, i presume we should make the last sentence a true "RFC"-MAY i.e. "Services MAY return delta links when this value has not been specified."

          What do you think?

          Update: I acknowledge the issue as applied in the current revision [OData Delta Query Protocol Design 2013-1-23.docx](https://www.oasis-open.org/committees/download.php/47996/OData%20Delta%20Query%20Protocol%20Design%202013-1-23.docx) .

          Show
          sdrees Stefan Drees (Inactive) added a comment - - edited Thanks a lot Mike, for already implementing the slightly edited version. The change you made (to the proposed wording), does help me better understand the described service. Another place that contributed as a source of the misinterpretation. Please inspect also (esp. the last sentence!): """ Requesting Delta Links An OData client may request that a service return delta links by including a Preference value of odata- request-deltas in the Prefer Header of the request. Services that support deltas should return a delta link, if possible for the request, but may ignore this value. Services may return delta links when this value has not been specified. """ So, i presume we should make the last sentence a true "RFC"-MAY i.e. "Services MAY return delta links when this value has not been specified." What do you think? Update: I acknowledge the issue as applied in the current revision [OData Delta Query Protocol Design 2013-1-23.docx] ( https://www.oasis-open.org/committees/download.php/47996/OData%20Delta%20Query%20Protocol%20Design%202013-1-23.docx ) .

            People

            • Assignee:
              mikep Michael Pizzo (Inactive)
              Reporter:
              sdrees Stefan Drees (Inactive)
            • Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: