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

Advertise non-availability of bound actions/functions

    Details

    • Type: Bug
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.0_ERRATA03
    • Fix Version/s: V4.01_WD01
    • Component/s: Vocabularies
    • Labels:
      None
    • Environment:

      Proposed

    • Proposal:
      Hide

      Advertise non-availability by providing null as the advertisement value:

      "#Model.FirstAction": {} --> available
      "#Model.SecondAction": null --> not available

      Note that services must only return the null value in a 4.01 or greater response.

      Show
      Advertise non-availability by providing null as the advertisement value: "#Model.FirstAction": {} --> available "#Model.SecondAction": null --> not available Note that services must only return the null value in a 4.01 or greater response.

      Description

      Actions and functions that are not available on all instances can be advertised in responses, see http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part1-protocol/odata-v4.0-errata03-os-part1-protocol-complete.html#_Toc453752309.

      Problem with current approach: does absence of an advertisement mean that an action/function is not available, or does it mean that the service doesn't advertise its availability?

        Attachments

          Activity

          Hide
          mikep Michael Pizzo (Inactive) added a comment -

          I like the simplicity of the default assumption that, if an operation is defined in metadata as bound to a type, it can be called on that type (it might return an error, but it's valid to call it).

          The question then becomes, if I have an operation that isn't always supported, how is it described? We know how it's advertised in payloads, but that payload needs to point back to metadata to describe parameters, return types, etc.

          Show
          mikep Michael Pizzo (Inactive) added a comment - I like the simplicity of the default assumption that, if an operation is defined in metadata as bound to a type, it can be called on that type (it might return an error, but it's valid to call it). The question then becomes, if I have an operation that isn't always supported, how is it described? We know how it's advertised in payloads, but that payload needs to point back to metadata to describe parameters, return types, etc.
          Hide
          handl Ralf Handl added a comment -

          The action/function advertisement is the pointer to metadata: the advertisement has the form of a URL fragment that identifies the action/function by its qualified name, and optionally by an additional list of non-binding parameter names to identify a specific overload

          {
          "@odata.context": "http://host/service/$metadata#Employees/$entity",
          "#Model.RemainingVacation": {},
          ...
          }

          or

          {
          "@odata.context": "http://host/service/$metadata#Employees/$entity",
          "#Model.RemainingVacation(Year)": {},
          ...
          }

          Show
          handl Ralf Handl added a comment - The action/function advertisement is the pointer to metadata: the advertisement has the form of a URL fragment that identifies the action/function by its qualified name, and optionally by an additional list of non-binding parameter names to identify a specific overload { "@odata.context": "http://host/service/$metadata#Employees/$entity", "#Model.RemainingVacation": {}, ... } or { "@odata.context": "http://host/service/$metadata#Employees/$entity", "#Model.RemainingVacation(Year)": {}, ... }
          Hide
          mikep Michael Pizzo (Inactive) added a comment -

          Today, by defining a bound action/function you are implying that you can construct the url for invoking the action or function, although the client may get an error if the bound instance is not in a valid state.

          If the intention is to call out cases where an instance is in a state where it cannot be invoked, perhaps an instance annotation to call out that the action/function is not supported on a particular instance.

          Perhaps we can use the existing syntax but specify a null value:

          "#Model.RemainingVacation": null

          Show
          mikep Michael Pizzo (Inactive) added a comment - Today, by defining a bound action/function you are implying that you can construct the url for invoking the action or function, although the client may get an error if the bound instance is not in a valid state. If the intention is to call out cases where an instance is in a state where it cannot be invoked, perhaps an instance annotation to call out that the action/function is not supported on a particular instance. Perhaps we can use the existing syntax but specify a null value: "#Model.RemainingVacation": null
          Hide
          mikep Michael Pizzo (Inactive) added a comment -

          Resolved as proposed 2016-10-13

          Show
          mikep Michael Pizzo (Inactive) added a comment - Resolved as proposed 2016-10-13
          Show
          handl Ralf Handl added a comment - Closed 2016-12-01, https://www.oasis-open.org/apps/org/workgroup/odata/download.php/59508/latest/odata-meeting-154_on-20161201-minutes.html

            People

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

              Dates

              • Created:
                Updated:
                Resolved: