Web API OData V4 Keys, Composite Keys and Functions Part 11

This article demonstrates how OData Functions can be used together with entities which have simple keys, composite keys, entity collections or used as plain simple global functions.

Part 1 Getting started with Web API and OData V4 Part 1.
Part 2 Web API and OData V4 Queries, Functions and Attribute Routing Part 2
Part 3 Web API and OData V4 CRUD and Actions Part 3
Part 4 Web API OData V4 Using enum with Functions and Entities Part 4
Part 5 Web API OData V4 Using Unity IoC, SQLite with EF6 and OData Model Aliasing Part 5
Part 6 Web API OData V4 Using Contained Models Part 6
Part 7 Web API OData V4 Using a Singleton Part 7
Part 8 Web API OData V4 Using an OData T4 generated client Part 8
Part 9 Web API OData V4 Caching Part 9
Part 10 Web API OData V4 Batching Part 10
Part 11 Web API OData V4 Keys, Composite Keys and Functions Part 11

Code: https://github.com/damienbod/WebApiODataFunctionsAndKeys

Basic Model and Entities

To demonstrate the different functions, with the different model types, a simple OData model is used with 2 Entities, a Stadium entity and a City entity. A namespace ‘D’ is defined because functions require a namespace. If not defined, the ‘Default’ namespace is used. I would prefer to use no namespace in the URL but this is not possible.

public static IEdmModel GetModel()
{
 ODataModelBuilder builder = new ODataConventionModelBuilder();
 builder.Namespace = "D";
 builder.ContainerName = "Default";
 EntitySetConfiguration<City> cities = builder.EntitySet<City>("City");
 EntitySetConfiguration<Stadium> stadiums = builder.EntitySet<Stadium>("Stadium");

The City entity has just a simple key property. This is the normal form.

[DataContract(Name = "City")]
public class City
{
 [DataMember]
 [Key]
 public int Id { get; set; }

 [DataMember]
 public long Population { get; set; }

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

The Stadium entity has a composite key made up of 2 key properties.

[DataContract(Name = "Stadium")]
public class Stadium
{
 [DataMember]
 [Key]
 public string Name { get; set; }

 [DataMember]
 [Key]
 public string Country { get; set; }

 [DataMember]
 public int Capacity { get; set; }

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

Web Configuration for IIS

The web.config needs some special configuration, if you want that the function URLs are reachable in the IIS. If not configured, you receive 404 for your URLs because the ‘.’ is not evaluated. The runAllManagedModulesForAllRequests is set to true.

<system.webServer>
  <modules runAllManagedModulesForAllRequests="true"></modules>
    <handlers>
      <remove name="ExtensionlessUrlHandler-Integrated-4.0" />
      <remove name="OPTIONSVerbHandler" />
      <remove name="TRACEVerbHandler" />
      <add name="ExtensionlessUrlHandler-Integrated-4.0" path="*." verb="*" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />
    </handlers>
</system.webServer>

OData Global Functions

These functions are the most simple of all the OData functions to setup. The functions are global and not connected to any entity or collection of entities. The global functions can be added directly to the model builder.

builder.Function("GlobalFunction")
   .ReturnsCollectionFromEntitySet<Stadium>("Stadium");

The global functions can then be made public inside any ODataController, the route must match the OData routes. This can be checked using the ~/odata/$metadata URL.

using System.Collections.Generic;
using System.Web.Http;
using System.Web.OData;
using System.Web.OData.Query;
using System.Web.OData.Routing;
using WebAPIODataKeys.Models;

namespace WebApiODataKeys.Controllers
{
    public class GlobalOdataFunctionsActionsController : ODataController
    {
		[EnableQuery(PageSize = 20, AllowedQueryOptions = AllowedQueryOptions.All)]
		[ODataRoute("GlobalFunction()")]
		[HttpGet]
		public IHttpActionResult GlobalFunction()
		{
			return Ok(new List<Stadium>{ new Stadium { Capacity = 2300, Country = "Switzerland", Name = "Times Stadium", Owner = "Global Owner" } });
		}
    }
}

~/odata/GlobalFunction()

webApifunctionsKeys_01

Collection Function which returns a Collection

OData functions can also be added to collections of entities. The following model configuration adds a GetStadiumsWithFunction function to the Stadium entity collection and returns a collection of stadium entities.

FunctionConfiguration getStadiumsWithFunction = stadiums.EntityType.Collection.Function("GetStadiumsWithFunction");
getStadiumsWithFunction.ReturnsCollectionFromEntitySet<Stadium>("Stadium");

The function is then made public in the Stadium ODataController. The URL contains the function namespace.

[EnableQuery(PageSize = 20, AllowedQueryOptions = AllowedQueryOptions.All)]
[ODataRoute("D.GetStadiumsWithFunction()")]
[HttpGet]
public IHttpActionResult GetStadiumsWithFunction()
{
   return Ok(new List<Stadium> { new Stadium { Capacity = 2300, Country = "Switzerland", Name = "Times Stadium", Owner = "FC Zug" } });
}

The function can then be used as follows:
~/odata/Stadium/D.GetStadiumsWithFunction()

webApifunctionsKeys_02

Collection Function which returns an Entity

This is very similar to the previous functions except this function has 2 input parameters and returns a single Stadium entity.

Function definition in the model:

// http://localhost:60096/odata/Stadium/D.GetStadiumTest(test='ddd', land='ssss')
FunctionConfiguration getStadiumsTest = stadiums.EntityType.Collection.Function("GetStadiumTest");
getStadiumsTest.Parameter<string>("test");
getStadiumsTest.Parameter<string>("name");
getStadiumsTest.ReturnsFromEntitySet<Stadium>("Stadium");

Function definition in the controller:

// http://localhost:60096/odata/Stadium/D.GetStadiumTest(test='ddd', land='ssss')
[ODataRoute("D.GetStadiumTest(test={test}, name={name})")]
[EnableQuery(PageSize = 20, AllowedQueryOptions = AllowedQueryOptions.All)]
[HttpGet]
public IHttpActionResult GetStadiumTest([FromODataUri] string test, [FromODataUri] string name)
{
  return Ok(new List<Stadium> { new Stadium { Capacity = 2300, Country = name, Name = test, Owner = "FC Zug" } });
}

~/odata/Stadium/D.GetStadiumTest(test=’ddd’, land=’ssss’)
webApifunctionsKeys_03

Entity Get with single key Entity

Before a function can be returned for a single entity, we need to know how to return the single entity in the controller. The key word can be used to match the single key property.

public IHttpActionResult Get(int key)
{
 return Ok(new City { Population = 9000000, Country = "Berlin", Id = key  });
}

This can then be used as follows:
~/odata/City(8)

Entity Function (Single key property)

The following example shows how to map a function to a single entity from type City. The function returns a Stadium entity.

FunctionConfiguration getStadiumFromCityWithFunction = cities.EntityType.Function("GetStadiumsFromCityWithFunction");
getStadiumFromCityWithFunction.ReturnsCollectionFromEntitySet<Stadium>("Stadium");

The function is added to the city controller, namespace included.

[EnableQuery(PageSize = 20, AllowedQueryOptions = AllowedQueryOptions.All)]
[ODataRoute("City({key})/D.GetStadiumsFromCityWithFunction()")]
[HttpGet]
public IHttpActionResult GetStadiumsFromCityWithFunction(int key)
{
  return Ok(new List<Stadium> { new Stadium { Capacity = 2300, Country = "Switzerland", Name = "Times Stadium", Owner = "FC Zug" } });
}

The function can be called as follows:
~/odata/City(8)/D.GetStadiumsFromCityWithFunction()

Entity Get with Composite keys Entity

The following controller method shows how to GET the composite Key entity. The key word cannot be used here because it has 2 separate key properties. The key properties have to be defined in the URL.

// http://localhost:60096/odata/Stadium(Name='Baz', Country='Germany')
[ODataRoute("(Name={name}, Country={country})")]
[EnableQuery(PageSize = 20, AllowedQueryOptions = AllowedQueryOptions.All)]
[HttpGet]
public IHttpActionResult Get([FromODataUri] string name, [FromODataUri] string country)
{
  return Ok(new Stadium { Capacity = 2300, Country = country, Name = name, Owner = "FC Zug" });
}

This can be called as follows:

~/odata/Stadium(Name=’Baz’, Country=’Germany’)

Entity Function with Composite keys Entity

Now that we know how to return a single entity for a composite entity, we can add a function to this and use it. The following method adds a function to the composite key entity Stadium.

FunctionConfiguration getCityFromStadiumWithFunction = stadiums.EntityType.Function("GetCityFromStadiumWithFunction");
getCityFromStadiumWithFunction.ReturnsFromEntitySet<City>("City");

This is then used in the Stadium ODataController.

// http://localhost:60096/odata/Stadium(Name='Baz', Country='Germany')/D.GetCityFromStadiumWithFunction()
[EnableQuery(PageSize = 20, AllowedQueryOptions = AllowedQueryOptions.All)]
[ODataRoute("(Name={name},Country={country})/D.GetCityFromStadiumWithFunction()")]
[HttpGet]
public IHttpActionResult GetCityFromStadiumWithFunction([FromODataUri] string name, [FromODataUri] string country)
{
 return Ok(new City { Population = 9000000, Country = "Berlin", Id = 8 });
}

This can then be called:
~/odata/Stadium(Name=’Baz’, Country=’Germany’)/D.GetCityFromStadiumWithFunction()

The full code example can be download with this link.

As you can see, OData Functions are very easy to use once you understand the design constraints and how the routing works.

Complete OData Model

public static IEdmModel GetModel()
{
	ODataModelBuilder builder = new ODataConventionModelBuilder();
	builder.Namespace = "D";
	builder.ContainerName = "Default";

	EntitySetConfiguration<City> cities = builder.EntitySet<City>("City");
	EntitySetConfiguration<Stadium> stadiums = builder.EntitySet<Stadium>("Stadium");

	// Per Collection Stadium
	FunctionConfiguration getStadiumsWithFunction = stadiums.EntityType.Collection.Function("GetStadiumsWithFunction");
	getStadiumsWithFunction.ReturnsCollectionFromEntitySet<Stadium>("Stadium");

	//  Per Collection Stadium, returns single entity
	FunctionConfiguration getStadiumsTest = stadiums.EntityType.Collection.Function("GetStadiumTest");
	getStadiumsTest.Parameter<string>("test");
	getStadiumsTest.Parameter<string>("name");
	getStadiumsTest.ReturnsFromEntitySet<Stadium>("Stadium");

	// Per Entity (Single key property) City
	FunctionConfiguration getStadiumFromCityWithFunction = cities.EntityType.Function("GetStadiumsFromCityWithFunction");
	getStadiumFromCityWithFunction.ReturnsCollectionFromEntitySet<Stadium>("Stadium");

	// Per Entity composite key Stadium
	FunctionConfiguration getCityFromStadiumWithFunction = stadiums.EntityType.Function("GetCityFromStadiumWithFunction");
	getCityFromStadiumWithFunction.ReturnsFromEntitySet<City>("City");

	// Global Function
	builder.Function("GlobalFunction").ReturnsCollectionFromEntitySet<Stadium>("Stadium");

	return builder.GetEdmModel();
}

Complete OData StadiumController

using System.Collections.Generic;
using System.Web.Http;
using System.Web.OData;
using System.Web.OData.Query;
using System.Web.OData.Routing;
using WebAPIODataKeys.Models;

namespace WebApiODataKeys.Controllers
{
	[ODataRoutePrefix("Stadium")]
	public class StadiumController : ODataController
	{
		[EnableQuery(PageSize = 20, AllowedQueryOptions = AllowedQueryOptions.All)]
		[HttpGet]
		[ODataRoute]
		public IHttpActionResult Get()
		{
			return Ok(new List<Stadium> { new Stadium { Capacity = 2300, Country = "Switzerland", Name = "Times Stadium", Owner = "FC Zug" } });
		}

		// GET odata/stadium?name=fds&country=Switzerland
		//[EnableQuery(PageSize = 20, AllowedQueryOptions = AllowedQueryOptions.All)]
		//[HttpGet]
		//public IHttpActionResult Get(string name, string country)
		//{
		//	return Ok(new Stadium { Capacity = 2300, Country = "Switzerland", Name = "Times Stadium", Owner = "FC Zug" });
		//}

		// http://localhost:60096/odata/Stadium(Name='Baz', Country='Germany')
		[ODataRoute("(Name={name}, Country={country})")]
		[EnableQuery(PageSize = 20, AllowedQueryOptions = AllowedQueryOptions.All)]
		[HttpGet]
		public IHttpActionResult Get([FromODataUri] string name, [FromODataUri] string country)
		{
			return Ok(new Stadium { Capacity = 2300, Country = country, Name = name, Owner = "FC Zug" });
		}

		// http://localhost:60096/odata/Stadium/D.GetStadiumTest(test='ddd', land='ssss')
		[ODataRoute("D.GetStadiumTest(test={test}, name={name})")]
		[EnableQuery(PageSize = 20, AllowedQueryOptions = AllowedQueryOptions.All)]
		[HttpGet]
		public IHttpActionResult GetStadiumTest([FromODataUri] string test, [FromODataUri] string name)
		{
			return Ok(new List<Stadium> { new Stadium { Capacity = 2300, Country = name, Name = test, Owner = "FC Zug" } });
		}

		[EnableQuery(PageSize = 20, AllowedQueryOptions = AllowedQueryOptions.All)]
		[ODataRoute("D.GetStadiumsWithFunction()")]
		[HttpGet]
		public IHttpActionResult GetStadiumsWithFunction()
		{
			return Ok(new List<Stadium> { new Stadium { Capacity = 2300, Country = "Switzerland", Name = "Times Stadium", Owner = "FC Zug" } });
		}

		// http://localhost:60096/odata/Stadium(Name='Baz', Country='Germany')/D.GetCityFromStadiumWithFunction()
		[EnableQuery(PageSize = 20, AllowedQueryOptions = AllowedQueryOptions.All)]
		[ODataRoute("(Name={name},Country={country})/D.GetCityFromStadiumWithFunction()")]
		[HttpGet]
		public IHttpActionResult GetCityFromStadiumWithFunction([FromODataUri] string name, [FromODataUri] string country)
		{
			return Ok(new City { Population = 9000000, Country = "Berlin", Id = 8 });
		}
	}
}

Complete OData CityController

using System.Collections.Generic;
using System.Web.Http;
using System.Web.OData;
using System.Web.OData.Query;
using System.Web.OData.Routing;
using WebAPIODataKeys.Models;

namespace WebApiODataKeys.Controllers
{
	public class CityController : ODataController
    {
		public IHttpActionResult Get()
		{
			return Ok(new List<City> { new City { Population = 2300000, Country = "Switzerland", Id=1} });
		}

		public IHttpActionResult Get(int key)
		{
			return Ok(new City { Population = 9000000, Country = "Berlin", Id = key  });
		}

		[EnableQuery(PageSize = 20, AllowedQueryOptions = AllowedQueryOptions.All)]
		[ODataRoute("City({key})/D.GetStadiumsFromCityWithFunction()")]
		[HttpGet]
		public IHttpActionResult GetStadiumsFromCityWithFunction(int key)
		{
			return Ok(new List<Stadium> { new Stadium { Capacity = 2300, Country = "Switzerland", Name = "Times Stadium", Owner = "FC Zug" } });
		}
    }
}

Links:

http://www.asp.net/web-api/overview/odata-support-in-aspnet-web-api/odata-routing-conventions

http://aspnet.codeplex.com/SourceControl/latest#Samples/WebApi/OData/v4/

http://blogs.msdn.com/b/odatateam/

7 comments

  1. I needed to implement composite keys and this example was perfect.

    However, the web developers want the json returned in camel case. I found an extension on odataconventionmodelbuilder:

    ODataConventionModelBuilder builder = new ODataConventionModelBuilder();
    builder.EnableLowerCamelCase();

    This gets us camel case, but when used together with the composite keys, the following exception is thrown in global.asax during start up when it gets to config.EnsureInitialized();

    An exception of type ‘System.InvalidOperationException’ occurred in System.Web.OData.dll but was not handled in user code
    Additional information: The path template ‘Stadium(Name={name}, Country={country})’ on the action ‘Get’ in controller ‘Stadium’ is not a valid OData path template. Bad Request – Error in query syntax.

    Has anyone ever come across this?

    1. Here is the solution: The lower camel case extension applies the renaming to the model members. For example, .MyPropertyName becomes .myProperyName.

      To account for what EnableLowerCamelCase() is doing, use an ODataRoute attribute like this on your controller:

      Stadium(name={name}, country={country})

      This in my opinion is a better solution than turning off the lower camel case setting and going back to large data models and renaming all properties to camelCase . (We still like to use PascalCase in our business code.)

  2. Great article about OData V4. Have you try accessing OData v4 using AngularJS?

    1. Not yet, sounds like a good idea.

      greetings Damien

  3. Ninos Denkha · · Reply

    Great article! However, if I host my app with OWIN or even your example project, then the route to D.GetStadiumTest(test={test}, name={nam}… ) returns HTTP 404 error. So, I wonder what’s the deal with OWIN hosting causing this issue? or what else do I need to set to make OWIN to work with custom OData functions.

    As a work around I had to delete my Startup.cs and put back Global.asax back. Hope to hear back from you.

    1. Hi Ninos, thanks. I could not get it the work without the global.asax configurations either. Seems to be a problem with the ODATA V4 implementation.

      annoying

      Greetings Damien

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: