Why is ODataRoutePrefix necessary?

[bdebaere]

Hi,

I was wondering why ODataRoutePrefix is necessary when using versioning for OData. Can't this value be determined by convention?

I have two controllers like below, version 1 and version 2.

[ApiVersion("1.0")]
[ODataRoutePrefix("Customers")]
public class CustomersController : ODataController
{
}

When I remove the ODataRoutePrefix line, the code no longer works. With the following error which doesn't even seem related.
The path template '({key})' on the action 'Get' in controller 'Customers' is not a valid OData path template. Empty segment encountered in request URL. Please make sure that a valid request URL is specified.

[commonsensesoftware]

API versioning doesn't make any changes to routing. Using attribute routing of any kind is not required with OData or otherwise. Attribute routing tends to be the more prolific form of routing now and also tends to easier to convey intent in examples. I use attribute routing in most of my examples (I believe), but it's by no means a requirement.

In order to help you further, I'd need to see the action for the route you are trying to define. It might also help if you can share/show the configuration bits relevant to OData and API Versioning (usually in WebApiConfig.cs).

[bdebaere]

@commonsensesoftware Thank you for your response.

Taking the code from SwaggerODataWebApiSample in your samples. If you remove the ODataRoutePrefix attribute, Swagger will give the error I specified earlier (The path template '({key})' on the action 'Get' in controller 'Customers' is not a valid OData path template. Empty segment encountered in request URL. Please make sure that a valid request URL is specified.) on:

        httpConfiguration.EnableSwagger(
                    "{apiVersion}/swagger",
                    swagger =>
                    {
                        // Build a swagger document and endpoint for each discovered API version.
                        swagger.MultipleApiVersions(
                            (description, version) => description.GetGroupName() == version,
                            info =>
                            {
                                foreach (ApiDescriptionGroup group in apiExplorer.ApiDescriptions)
// Error on this line.
                                {
                                    if (group.IsDeprecated)
                                    {
                                        apiDescription += " This version has been deprecated!";
                                    }

                                    info.Version(group.Name, $"{apiName} {group.ApiVersion}")
                                        .Description(apiDescription);
                                }
                            });
                    })
                .EnableSwaggerUi(swagger => swagger.EnableDiscoveryUrlSelector());

My controller has 2 Get functions like any standard OData controller:

        [ODataRoute]
        [EnableQuery(MaxExpansionDepth = 10)]
        public virtual IQueryable<Customer> Get()
        {
            return _repository.Select();
        }

        [ODataRoute("({key})")]
        [EnableQuery(MaxExpansionDepth = 10)]
        public virtual SingleResult<Customer> Get([FromODataUri] int key)
        {
            IQueryable<Customer> result = _repository.Select(key);
            return SingleResult.Create(result);
        }

[bdebaere]

Any update here?

[commonsensesoftware]

Apologies, it seems I missed your reply. I'll take a look at this. On the surface, this looks ok to me. Can you share your Web API and OData configuration too? Thanks

[bdebaere]

@commonsensesoftware I'm not completely sure what you are requesting. But I basically followed the SwaggerODataWebApiSample.

            httpConfiguration
                .Count()
                .Filter()
                .OrderBy()
                .Expand()
                .Select()
                .MaxTop(null);

            httpConfiguration.AddApiVersioning(
                    setting =>
                    {
                        setting.AssumeDefaultVersionWhenUnspecified = true;
                        // This assumes the default to be the first version.
                        // TODO: the alternative is o => o.ApiVersionSelector = new CurrentImplementationApiVersionSelector(o)
                        setting.DefaultApiVersion = ApiVersion.Default;
                        // Adds HTTP headers "api-supported-versions" and "api-deprecated-versions" to the response.
                        setting.ReportApiVersions = true;
                    }
            );

            VersionedODataModelBuilder modelBuilder = new VersionedODataModelBuilder(httpConfiguration)
            {
                ModelBuilderFactory = () => new ODataConventionModelBuilder(),
                ModelConfigurations = { modelConfiguration }
            };  

            List<IEdmModel> models = modelBuilder.GetEdmModels().ToList();

            httpConfiguration.MapVersionedODataRoutes("odata", "", models, EnableUnqualifiedCaseInsensitiveUri);
            httpConfiguration.MapVersionedODataRoutes("odata-bypath", "v{apiVersion}", models, EnableUnqualifiedCaseInsensitiveUri);

        private static void EnableUnqualifiedCaseInsensitiveUri(IContainerBuilder containerBuilder)
        {
            containerBuilder.AddService(ServiceLifetime.Singleton, typeof(ODataUriResolver), sp => new UnqualifiedCaseInsensitiveUriResolver());
        }

[bdebaere]

@commonsensesoftware Hi, do you have any update?

[commonsensesoftware]

It's unclear to me if you are trying route by convention or using attributes. To my knowledge, OData will let you mix and match, but it doesn't fill in the blanks if you don't provide all of the attributes. You either provide all of the attributes or none of them.

In your scenario, since you've applied the [ODataRoute] attribute to your routes, you need to do one of the following:

• Add the entity set name to your routes (ex: [ODataRoute("Customers")])
• Add the [ODataRoutePrefix("Customers")] to your controller so you don't need to repeat the prefix for the route on each action

Now, if you want to route purely by convention, that is meant to be a supported scenario. However, in putting together an example for you, I found a bug. You can track it in issue #226. The bug only affects convention-only routing. I likely missed this scenario for Swagger since attribute routing is far more popular.

[bdebaere]

@commonsensesoftware Routing by convention (CustomersController => Customers) is something I would always prefer.

I originally added the [ODataRoute] attribute to my GET functions because Swagger was complaining with the following error message

500 : {"Message":"An error has occurred.","ExceptionMessage":"Not supported by Swagger 2.0: Multiple operations with path 'Customers' and method 'GET'. See the config setting - "ResolveConflictingActions" for a potential workaround"

Is there a way to have both routing by convention and Swagger to work properly?

[commonsensesoftware]

Apologies for the delay, there were a lot of little issues of resolve. A new version of the packages are now available. I've also update the OData Swagger example, which demonstrates the "Orders" service using attribute-routing and the "People" service using convention-routing. I've also thrown in a few functions and actions to show off new features. Let me know if you have any questions.

[bdebaere]

@commonsensesoftware Why is routing by convention the least popular? I assume it is less work and prevents issues with naming from happening for example where your route attribute differs from the name of your controller. Am I wrong to prefer convention based routing?

You will never get the error I had because you only have one GET method in your controller in your samples. If you add a Get(int key) you will receive the error that I mentioned if you use the previous version of aspnet-api-versioning.

I assume you just pushed the update to the ApiExplorer NuGet packages. I can use convention based routing since I updated my packages.