The biggest enhancement to the WebApi Extension in 3.0 is the support for OData queries.
A new controller has been added MicroLiteODataApiController<TEntity, TId>
which is in the MicroLite.Extensions.WebApi.OData
namespace. This extends the base MicroLiteApiController<TEntity, TId>
so you can add OData support to “entity” controllers.
As per the MicroLiteApiController<TEntity, TId>
, the OData support is opt-in so you need to create a public method called Get which accepts a parameter of ODataQueryOptions
and calls the base class to return the response
public HttpResponseMessage Get(ODataQueryOptions queryOptions)
{
return this.GetEntityResponse(queryOptions);
}
The following query options are currently supported:
- $filter
- $format
- $inlinecount
- $orderby
- $select
- $skip
- $top
Given the following class:
public class Customer
{
public int CustomerId { get; set; }
public string Forename { get; set; }
public string Surname { get; set; }
public DateTime Joined { get; set; }
}
and the corresponding controller:
public class CustomerController : MicroLiteODataApiController<Customer, int>
{
public CustomerController()
{
// This MaxTop will default to 50 if not otherwise specified & will be used to limit the max value
// allowed in $top or constrain the results if no $top is specified in the OData query.
this.ValidationSettings.MaxTop = 100;
}
public HttpResponseMessage Get(ODataQueryOptions queryOptions)
{
return this.GetEntityResponse(queryOptions);
}
}
The ValidationSettings property allows you to limit the query options which can be used with the controller and also limit the number of results returned per request.
Example queries:
$select – this allows you to limit which properties are returned in the query, if no $select value is specified, all properties will be included. Property names must be cased correctly.
URI: /api/customer?$select=CustomerId,Forename,Surname
would return results such as
[{ "CustomerId": 1, "Forename": "John", "Surname": "Smith" }, { "CustomerId": 2, "Forename": "Joe", "Surname": "Bloggs" } ]
This means that the result set won’t contain properties that you have not specified so you won’t get default values returned in property values which haven’t been retrieved from the database and makes the response payload smaller.
$filter – this allows you to constrain the results returned based upon specified predicates, if no $filter value is specified, all results will be returned (up to the maximum supported by the controller)
URI /api/customer?$filter=Joined gt datetime'2010-01-01' and Surname eq 'Smith'
would return all customers with the surname Smith who joined after 1st Jan 2010.
$skip and $top can be used to constrain the number of results returned to implement paging e.g:
URI /api/customer?$skip=50&$top=50
$orderby – this allows you to specify how the results are ordered in the result set
URI /api/customer?$orderby=Surname, Joined desc
would sort by Surname ascending and then within each Surname, Joind date descending.
If not specified, the order will default to ascending. If specified, the order must be asc or desc
$format – allows you to override the format the data should be returned in regardless of the value in the content-type HTTP header:
regardless of the content-type header value, return the results in JSON:
URI /api/customer?$format=json
regardless of the content-type header value, return the results in XML:
URI /api/customer?$format=xml
$inlinecount – allows you to ask the results to be returned along with a total count of the results. If not specified, no inline count will be used
URI /api/customer?$inlinecount=allpages
include in the results a property called count which contains the total number of results
URI /api/customer?$inlinecount=none
do not include a count in the results – this is the default behavior if not specified.
The query options can be combined to filter results however you like, BUT each option may only appear once.