[OASIS Issue Tracker] Updated: (ODATA-258) Advertise function imports in service document

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

     [ http://tools.oasis-open.org/issues/browse/ODATA-258?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Michael Pizzo updated ODATA-258:
--------------------------------

    Proposal: 
1. Define a new boolean attribute to FunctionImport called "IncludeInServiceDocument", valid only on parameterless functions. If present, with a value of "True", the function import is advertised in the service document
2. Define a new kind "Function", in ATOM and JSON, for exposing parameterless functions
3. Clarify that the service SHOULD NOT expose entitysets that cannot be navigated using only the supplied href.

Examples:

{
  "odata.metadata": "http://host/service/$metadata";,
  "value": [
    { 
      "name": "Orders",
      "kind": "EntitySet"
      "url": "Orders"
    },
    {
      "name": "TopProducts",
      "kind": "Function"
      "url": "TopProducts"
    },
    {
      "name": "Contoso",
      "kind": "Entity"
      "url": "Contoso"
    }
  ]
}

  was:
In addition to entity sets and named entities also top-level function imports (i.e. that don't require a binding parameter) from the default entity container are advertised in the service document. These use the new kind "Function".

Examples:

{
  "odata.metadata": "http://host/service/$metadata";,
  "value": [
    { 
      "name": "Orders",
      "kind": "EntitySet"
      "url": "Orders"
    },
    {
      "name": "TopProducts",
      "kind": "Function"
      "url": "TopProducts"
    },
    {
      "name": "Contoso",
      "kind": "Entity"
      "url": "Contoso"
    }
  ]
}


I like advertising parameterless functions, but I would make it explicit, rather than automatically exposing based on the defined parameters.

The Service Document should be for clients that are just following hyperlinks w/o any specific knowledge of OData conventions, etc., so we should not advertise functions that require parameters. I would not special case parameters with defaults at this point; we can add that later if it's a compelling scenario.

Note that, by the same token, entitysets that are not queryable, or that require specialy semantics (such as querying on a particular property), should not be advertised in the service document.


> Advertise function imports in service document
> ----------------------------------------------
>
>                 Key: ODATA-258
>                 URL: http://tools.oasis-open.org/issues/browse/ODATA-258
>             Project: OASIS Open Data Protocol (OData) TC
>          Issue Type: Improvement
>          Components: OData ATOM Format v1.0, OData JSON Format v1.0
>    Affects Versions: WD01
>         Environment: [Proposed]
>            Reporter: Ralf Handl
>             Fix For: WD01
>
>
> The service document is an entry point for hypermedia-driven clients, so function imports that can be called "directly from the service root" should also be advertised.
> Function imports that require a binding parameter don't fall into that category.
> Ideally the advertised function imports would require no parameters to be passed, i.e. only have parameters with default values or no parameters at all, so they behave to GET requests similar to named entities and entity sets.
> As in real life we also encounter entity sets that e.g. respond with errors if queried without a sufficiently selective $filter query parameter, I hesitate to make "only parameters with default values" a requirement for being advertised.

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira