Getting started¶
This guide will help you get started with FunQL .NET quickly.
Installation¶
1. Create a new Web API project¶
Create a new ASP.NET Core Web API project using the .NET CLI.
This will create a new directory called Demo
containing your project's files.
You can now open the Demo
directory or the Demo.csproj
file in your favourite code editor.
2. Add the FunQL package¶
Add the FunQL package to your
project using the .NET CLI:
Note
This will install both FunQL.Core and FunQL.Linq, providing all the essential components to get you started quickly.
Create the data model¶
For this example we'll create an API for querying LEGO sets, so create a Set
data model.
Create the schema¶
A schema defines the structure and behavior of your API, including the available requests, their parameters, and the
data models they operate on. Create a schema and add the Core
and LINQ
features to enable query parsing, validation,
and execution. Then add the listSets
request with support for filtering and sorting, ready to query Set
data.
public sealed class DemoSchema : Schema
{
protected override void OnInitializeSchema(ISchemaConfigBuilder schema)
{
// ===== Features =====
// Add all core features: Parse, Print, Validate, Visit and Execute
schema.AddCoreFeatures();
// Add LINQ feature so FunQL can translate FunQL queries to LINQ expressions, e.g. for use with EFCore DbSet
schema.AddLinqFeature();
// ===== Requests =====
// Add the 'listSets()' request
schema.Request("listSets")
// Enable support for the 'filter()' parameter
.SupportsFilter()
// Enable support for the 'sort()' parameter
.SupportsSort()
// Configure the 'listSets()' return type: 'List<Set>'
.ReturnsListOfObjects<Set>(set =>
{
// Configure each field of the data model
set.SimpleField(it => it.Name)
.HasName("name")
.SupportsFilter(it => it.SupportsStringFilterFunctions())
.SupportsSort(it => it.SupportsStringFieldFunctions());
set.SimpleField(it => it.Price)
.HasName("price")
.SupportsFilter(it => it.SupportsDoubleFilterFunctions())
.SupportsSort(it => it.SupportsDoubleFieldFunctions());
set.SimpleField(it => it.LaunchTime)
.HasName("launchTime")
.SupportsFilter(it => it.SupportsDateTimeFilterFunctions())
.SupportsSort(it => it.SupportsDateTimeFieldFunctions());
});
}
}
Add FunQL services¶
In Program.cs
, add the DemoSchema
as a singleton to the application services, ready to be injected in request
handlers.
Create a REST endpoint with FunQL support¶
With the DemoSchema
fully configured, we can use it to create a REST endpoint to filter and sort LEGO sets. Update
Program.cs
to add the /sets
endpoint to filter and sort a list of LEGO sets.
app.MapGet("/sets", async (string filter, string sort, DemoSchema schema) =>
{
// We use demo data for this example — Normally you would e.g. use an Entity Framework Core DbContext to query the
// database directly
IQueryable<Set> sets = new List<Set>
{
new("LEGO Star Wars Millennium Falcon", 849.99, DateTime.Parse("2017-10-01", styles: DateTimeStyles.AdjustToUniversal)),
new("LEGO Star Wars The Razor Crest", 599.99, DateTime.Parse("2022-10-03", styles: DateTimeStyles.AdjustToUniversal)),
new("LEGO DC Batman Batmobile Tumbler", 269.99, DateTime.Parse("2021-11-01", styles: DateTimeStyles.AdjustToUniversal)),
new("LEGO Harry Potter Hogwarts Castle", 469.99, DateTime.Parse("2018-09-01", styles: DateTimeStyles.AdjustToUniversal)),
}.AsQueryable();
var result = await sets
.ExecuteRequestForParameters(
schema,
requestName: "listSets",
filter: filter,
sort: sort
);
return result.Data;
});
And that is it, you have now successfully added FunQL support to your API! 🚀
Execute a query¶
Run the project using the .NET CLI:
If everything is set up correctly, you should be able to open http://localhost:5000/sets to query the LEGO sets. Looking for LEGO Star Wars sets that cost at least €500 and were launched after 2010, sorted by price? Just ask: