[OASIS Issue Tracker] Created: (ODATA-425) Clarify rules around parameter overloads and return types

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

Clarify rules around parameter overloads and return types
---------------------------------------------------------

                 Key: ODATA-425
                 URL: http://tools.oasis-open.org/issues/browse/ODATA-425
             Project: OASIS Open Data Protocol (OData) TC
          Issue Type: Bug
          Components: OData CSDL
    Affects Versions: V4.0_CSD01
         Environment: [Proposed]
            Reporter: Michael Pizzo
             Fix For: V4.0_CSD02


Functions and actions today support overloads. Actions overloads must differ by binding parameter, function overloads must differ by a unique combination of parameter names.

We don't say anything today about whether or not different overloads of the same function/action can return the same type.

There are scenarios where it is interesting for multiple function/action overloads to return the same type (for example, a "GetByID" function or "Create" action bound to a collection of entities of a certain type). However, supporting overloads within a path makes it impossible for a simple parser to know the types of the segments; something a parser with metadata information should be able to do. As a general rule, the segments of a path should be strongly typed.

There is a fairly simple solution to these two seemingly incongruous requirements; the scenarios in which it is interesting to vary the return type by overload are exactly the scenarios in which we have a binding parameter. And, if we have a binding parameter, and we know the type of each segment, we know the overload from parsing just the path.

The one exception to this rule is the fact that we currently support a legacy style of passing parameters by name in the query string without defining aliases in the path. For example, we currently support:

    ~Customers/GetById?id='ALFKI'

This third way of binding parameters is only supported for a function/action in the final segment and its only usefulness is that a service could advertise a function/action, and the client could call it without having to parse the path and see what names were chosen for the parameters.

The solution to this scenario is to require that advertised functions/actions utilize parameter markers named according to the parameter names defined in metadata. So, for example, if a function "GetById" takes a parameter named "Id", then the advertised form of the function, following convention, would be:
    ~Customers/GetById(id=@id)
and the client would call by providing the id parameter in the query string:
    ~Customers/GetById(id=@id)?@id='ALFKI'

This simplifies the current model by removing a third variation of parameter passing that is restricted only to a narrow usage and at the same time ensuring that the functions within a path are always strongly typed.


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