Using Linq2Rest

Tags: Linq2Rest, LINQ, REST, Web

When I published the release version of Linq2Rest, I knew that this was only the technical side of the project. In order for a project to be useful (or even used), user must be able to get started with it. I've tried to keep the API as simple as possible. Primarily because it makes it easier to use, but also because it makes it easier to manage from a semantic versioning perspective.

First of all, what is Linq2Rest? Linq2Rest parses a set of query parameters conforming to the OData protocol and converts them into a LINQ filter, which can be used to filter a data source. For a simple data source such as a List or T[] it works like any other LINQ query, but if you use it with ORM frameworks, they can apply it as a SQL query to the database. This means that you can expose your data in a much richer way to your users than merely by relying on some obscure parameters written in your documentation, that they will never read. Linq2Rest also works on the client side by exposing a LINQ provider that will generate OData compliant web requests to a given host.

So what is required to parse a given request into a LINQ filter? Obviously you must be running a web site (ASP.NET) that the user can request data from. ASP.NET MVC is also supported, more on that later. To apply the LINQ filter to your data source, simply use the Filter extension method on your LINQ compatible data source, like so:

var filteredSource = source.Filter(Request.Params);

Linq2Rest parses the passed NameValueCollection (in this case the parameters of the current request) and gets all OData parameters and creates an expression tree from them which is applied to the source. Note that the returned filteredSource, is an IEnumerable and not necessarily the same as your original source, since OData supports data projection and the exact return type cannot be known before the filter is applied.

If you are running an ASP.NET MVC site, your action can also reference the current request directly and retrieve the query parameters, but it is not considered very good practice. Instead it is recommended that you add an IModelFilter to the actions where you wish to apply filtering. So your action could look something like this:

public ActionResult Index(IModelFilter<yourobjecttype> filter, IEnumerable<yourobjecttype> source)
{
    var filteredSource = source.Filter(filter);
    return View(filteredSource);
}

In order for the MVC Framework to create an IModelFilter for your request, you will need to add a model binder to your MVC application. The Linq2Rest.Mvc nuget package gives you access to a model binder which performs this binding for you, all you need to do is add it to your application like any other model binder:

protected void Application_Start()
{
	AreaRegistration.RegisterAllAreas();

	RegisterGlobalFilters(GlobalFilters.Filters);
	RegisterRoutes(RouteTable.Routes);

	var binder = new ModelFilterBinder<yourobjecttype>(new ParameterParser<yourobjecttype>());
        ModelBinders.Binders.Add(typeof(IModelFilter<yourobjecttype>), binder);
}

The model binder will be invoked when a request is received and will create the filter for the given request, which you can then apply as shown above.

Linq2Rest is published under Microsoft Public License and can be found on BitBucket and Nuget (The Linq2Rest.Mvc project on Nuget).

Latest Tweets