Skip to content

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.

dotnet new webapi -n Demo

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 NuGet package to your project using the .NET CLI:

dotnet add package FunQL

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.

public sealed record Set(string Name, double Price, DateTime LaunchTime);

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.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<DemoSchema>();

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:

dotnet run

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:

http://localhost:5000/sets
    ?filter=and(has(upper(name), "STAR WARS"), gte(price, 500), gt(year(launchTime), 2010))
    &sort=desc(price)