OData Function Versioning

[Zaheer-hawseea]

Hi,
I'm trying to version a function in OData whereby the function has different parameters depending on the version. However below error is obtained when HttpConfiguration.EnsureIsInitialized() is called. Your help will be greatly appreciated.

Error : The path template 'GetPerson(fname={fname}, lname={lname})' on the action 'GetPerson' in controller 'GetPerson' is not a valid OData path template. Resource not found for the segment 'GetPerson'.

Entity:

[DataContract]
public class Person
{
   [Key]
   [DataMember]
   public int Id { get; set; }

   [DataMember]
   public string FirstName { get; set; }

   [DataMember]
   public string LastName { get; set; }
}

public class PersonModelConfiguration : IModelConfiguration
    {
        public void Apply(ODataModelBuilder builder, ApiVersion apiVersion)
        {
            builder.EntitySet<Person>("Person");

            if (apiVersion.MajorVersion == 1)
            {
                var config1 = builder.Function("GetPerson");
                config1.Parameter<string>("id");
                config1.ReturnsFromEntitySet<Person>("Person");
            }
            else
            {
                var config2 = builder.Function("GetPerson");
                config2.Parameter<string>("fname");
                config2.Parameter<string>("lname");
                config2.ReturnsFromEntitySet<Person>("Person");
            }
        }
    }

public void Configuration(IAppBuilder app)
       {
           // Server configuration
           HttpConfiguration config = new HttpConfiguration();

           config.AddApiVersioning(o => {
               o.AssumeDefaultVersionWhenUnspecified = true;
               o.ReportApiVersions = true;
               o.ApiVersionReader = ApiVersionReader.Combine(
                       new QueryStringApiVersionReader(),
                       new HeaderApiVersionReader("api-version", "x-ms-version")
                   );
           });

           // OData Model Builder
           var builder = new VersionedODataModelBuilder(config)
           {
               ModelBuilderFactory = () => new ODataConventionModelBuilder().EnableLowerCamelCase(),
               ModelConfigurations = { new PersonModelConfiguration() }
           };

           var options = config.GetApiVersioningOptions();

           var v1 = new ApiVersion(1, 0);
           var v2 = new ApiVersion(2, 0);

           options.Conventions.Controller<GetPersonController>()
               .HasApiVersion(v1)
               .HasApiVersion(v2)
               .Action(a => a.GetPerson(default(string))).MapToApiVersion(v1)
               .Action(a => a.GetPerson(default(string), default(string))).MapToApiVersion(v2);

           var models = builder.GetEdmModels();

           // Map OData in OWin
           config.MapVersionedODataRoutes("Default-ODataRoute", "api", models);
           config.MapVersionedODataRoutes("ODataRoute-Versioned", "api/v{apiVersion}", models);

           config.EnsureInitialized();
           app.UseWebApi(config);
       }

public class GetPersonController : ODataController
   {
       private static Person testPerson1 = new Person() {Id = 1, FirstName = "James", LastName = "Brown"};
       private static Person testPerson2 = new Person() {Id = 2, FirstName = "Paul", LastName = "Allen"};

       [HttpGet]
       [ODataRoute("GetPerson(id={id})")]
       public async Task<IHttpActionResult> GetPerson([FromODataUri] string id)
       {
           var person = await Task.FromResult(testPerson1);

           return Ok(person);
       }

       [HttpGet]
       [ODataRoute("GetPerson(fname={fname}, lname={lname})")]
       public async Task<IHttpActionResult> GetPerson([FromODataUri] string fname, [FromODataUri] string lname)
       {
           var person = await Task.FromResult(testPerson2);

           return Ok(person);
       }
   }

[Zaheer-hawseea]

Note: using attributes ApiVersion and MapToApiVersion in the controller gives the same error.

[d-saravanan]

Did you try out the Advanced Web API OData sample app

[Zaheer-hawseea]

The advanced sample does not help since it only define get methods on entities itself. Here i'm trying to define a function which imply to explicitly specify the function to the ODataModelBuilder. for e.g. ODataModelBuilder.function("Name").Parameters("").Returns("")..

[commonsensesoftware]

Do you have a working example without API versioning? I will help to take versioning out of the picture first to make sure the route templates are correct.

[commonsensesoftware]

I managed to get a function working without API versioning, but the same setup seems to fail with API versioning. I'm not sure what that's happening yet. The pairing is pretty simple. It's EdmModel to ApiVersion. It's unclear why this is happening. I'll dig deeper. This might be a bug.

[Zaheer-hawseea]

In the model configuration, if both functions are added for version 1 and 2 (i.e. the check on major version is removed), then the error is not obtained but this defeat the purpose of versioning since then there are 2 functions in both versions. Meaning someone using version 1 of the api, will also see the function for version 2 and vice versa. The $metadata then will contain duplicates..

[jaw2255]

Hello, I'm wondering if there has been any further progress made on this issue? I have just started implementing versioning for my existing OData Web API w/ Swagger, and it has a handful of functions. I'm not getting any errors on the configuration or build but whenever I open up the function in swagger, it's adding the Controller name to beginning of the function, even as an unbound function. For example, I have a Controller Class called "Functions" , and a function inside the controller named "Geocode", When I open up Swagger the function shows up like this "api/v{apiVersion}/FunctionsGeocode(Address={address})". The previous version of my Web API it would just show up as " /api/v{apiVersion}/Geocode(Address={address})". When I test the function I just get a 404 Not Found. Greatly appreciate any help or tips..

[commonsensesoftware]

Apologies for the delay on this issue. I haven't forgotten about it, I've just been up my eyeballs. My cursory examination suggests that there is, in fact, a bug in resolving the functions from the EDM. The investigation appears deep, which is why I've been forced to continue punting on knocking it out. I'll be taking some time off for the holidays, so I'm hoping to commit a day or two resolving this. Apologies again, I know some folks have been waiting on this for some time.

[commonsensesoftware]

So sorry for the long update and resolution to this issue. You've probably opted for another route or workaround. Regardless, I've finally tracked down the issue. Ultimately, the default attribute routing conventions do not support action filtering. See the original Line 228. With this implementation, API version interleaving will not work because all functions are considered, but they may not exist in the EDM model.

I vaguely remember trying to replace this entire class, but seemingly encountered a reason why I couldn't. Whatever the reason was, the constraint seems to be removed now. Perhaps it was something that changed between 5.9.x and 6.0.x.

It appears that it was possible to make things work as is, but only if you split the actions across different controller types. Since API version interleaving with a single controller type is a supported scenario, I'm officially calling the existing behavior a bug.

I have a rough skeleton of a working fix. I should have this resolved soon. There are a couple of bugs in the queue I'm working on combining for the next release, but expect to see things published by the end of next week at the latest.

[commonsensesoftware]

@jaw2255 is your issue related to invoking a versioned OData function or just the Swagger integration? From your description, it sounds like it might be Swagger-specific. If that's the case, I think we should open a new, separate issue to track it. Let me know.

[commonsensesoftware]

@Dev00071 I was able to verify your scenario is working with the fix. As soon as I publish the update, all should be good. In case it's still relevant, there are a couple of other points worth mentioning.

1. You don't need to register the OData routes twice unless you really want both API versioning styles. I do this in the samples purely for illustrative purposes so that I don't need two different examples. This seems to confuse some folks, so I may need to add a clarifying comment in the sample.
2. While you can get the API versioning options outside of the initialization method, it's not recommended that you make changes to the options after initialization. There is no guarantee that things will work as expected if you do that. You should define all conventions within the initialization method. If you want to break things up, just extract the conventions to another method that is called in the initialization method. The conventions are only applied once. Configuring them later may result in them not being applied.

[commonsensesoftware]

I made a few minor changes to the basic OData example for the verification. Here were the relevant changes:

// unbounded functions with API versioning
public class GetPersonController : ODataController
{
    [HttpGet]
    [ODataRoute( "GetPerson(id={id})" )]
    public IHttpActionResult GetPerson( [FromODataUri] int id ) =>
        Ok( new Person() { Id = id, FirstName = "Bill", LastName = "Mei", Email = "[email protected]", Phone = "555-555-5555" } );

    [HttpGet]
    [ODataRoute( "GetPerson(fname={fname},lname={lname})" )]
    public IHttpActionResult GetPerson( [FromODataUri] string fname, [FromODataUri] string lname ) =>
        Ok( new Person() { Id = 42, FirstName = fname, LastName = lname, Email = "[email protected]", Phone = "555-555-5555" } );
}

// convention definitions moved into the initialization method
configuration.AddApiVersioning(
    options =>
    {
        options.ReportApiVersions = true;
        options.Conventions.Controller<GetPersonController>()
                            .HasApiVersion( 1, 0 )
                            .HasApiVersion( 2, 0 )
                            .Action( c => c.GetPerson( default( int ) ) ).MapToApiVersion( 1, 0 )
                            .Action( c => c.GetPerson( default( string ), default( string ) ) ).MapToApiVersion( 2, 0 );
    } );

[jaw2255]

Hey Chris, Thanks for the work on this! I'm just getting back from vacation and I'll see if I can get your fix working with my code.

…

-John

________________________________ From: Chris Martinez <[email protected]> Sent: Thursday, December 28, 2017 2:07 PM To: Microsoft/aspnet-api-versioning Cc: jaw2255; Mention Subject: Re: [Microsoft/aspnet-api-versioning] OData Function Versioning (#201) @Dev00071<https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fdev00071&data=02%7C01%7C%7C56b3c87f54344e51c83a08d54e263e91%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636500848517097385&sdata=uF9rfthsC3Zf%2BIooSw9OjtRYyIjVOVUb1prO6rC2v%2Fs%3D&reserved=0> I was able to verify your scenario is working with the fix. As soon as I publish the update, all should be good. In case it's still relevant, there are a couple of other points worth mentioning. 1. You don't need to register the OData routes twice unless you really want both API versioning styles. I do this in the samples purely for illustrative purposes so that I don't need two different examples. This seems to confuse some folks, so I may need to add a clarifying comment in the sample. 2. While you can get the API versioning options outside of the initialization method, it's not recommended that you make changes to the options after initialization. There is no guarantee that things will work as expected if you do that. You should define all conventions within the initialization method. If you want to break things up, just extract the conventions to another method that is called in the initialization method. The conventions are only applied once. Configuring them later may result in them not being applied. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FMicrosoft%2Faspnet-api-versioning%2Fissues%2F201%23issuecomment-354339895&data=02%7C01%7C%7C56b3c87f54344e51c83a08d54e263e91%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636500848517097385&sdata=v6wHQjNQHNUbMCLOfYwwzwVcNCmB5CQuMO5p12HP1Hs%3D&reserved=0>, or mute the thread<https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAI1H-TNvELpBTn4Tty_OsUwO1M11ojo1ks5tE-bwgaJpZM4Pq4jM&data=02%7C01%7C%7C56b3c87f54344e51c83a08d54e263e91%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636500848517097385&sdata=6GhjSMqCnrJxTtWmHM7nQF%2FdpGUuJqSVCt8tHkyo1u0%3D&reserved=0>.

[Zaheer-hawseea]

Thank you chris, greatly appreciate. Let know when the new package is available 👍

[commonsensesoftware]

The new packages with this fix have been published. Let me know if you encounter any new issues.