ApiQueryOptions 1.0.0-beta5

ApiQueryOptions

Lightweight OData-style query parameter parsing for ASP.NET Core REST APIs — without the overhead of a full OData stack.

Parses $filter, $expand, $orderby, $top, $skip, and $skiptoken from HTTP query strings and applies them to any IQueryable<T> as deferred LINQ expression trees. Nothing is enumerated until you call .ToList() or .ToListAsync().

For EF Core support ($expand → .Include()), see ApiQueryOptions.EntityFrameworkCore.

Installation

dotnet add package ApiQueryOptions

Quick start

1. Register in Program.cs

builder.Services.AddControllers();
builder.Services.AddApiQueryOptions();

Restrict options globally:

builder.Services.AddApiQueryOptions(new ApiQueryOptionsSettings
{
    ExpandEnabled    = false,
    SkipTokenEnabled = false,
    MaxPageSize      = 100,
    DefaultPageSize  = 25,
});

2. Accept options in a controller action

[HttpGet]
public IActionResult Get(ApiQueryOptions<Product> options)
{
    List<Product> items = _db.Products.Apply(options).ToList();
    return Ok(new { value = items, nextLink = options.NextLink(items.Count) });
}

3. Override settings per action or controller

[ApiController]
[Route("api/[controller]")]
[ApiQueryOptions(DefaultPageSize = 20, MaxPageSize = 100)]
public class ProductsController : ControllerBase
{
    [HttpGet]
    public IActionResult Get(ApiQueryOptions<Product> options) { ... }

    // Method-level attribute wins over controller-level
    [HttpGet("archive")]
    [ApiQueryOptions(MaxPageSize = 500, FilterEnabled = QueryOptionState.Disabled)]
    public IActionResult GetArchive(ApiQueryOptions<Product> options) { ... }
}

Unset properties (0 for integers, QueryOptionState.Default for toggles) inherit from the registered settings unchanged.

Supported query parameters

Both the $-prefixed OData form ($filter=...) and the bare form (filter=...) are accepted.

Filter syntax

Comparison operators

String eq/ne comparisons respect the StringComparison in ApiQueryOptionsSettings (default: OrdinalIgnoreCase).

Logical operators

$filter=Age gt 18 and Age lt 65
$filter=Status eq 'Active' or Status eq 'Pending'
$filter=(Region eq 'US' or Region eq 'CA') and IsActive eq true

String functions

Literal types

Dotted property paths

$filter=Address.City eq 'Seattle'

Pagination

Offset-based ($top + $skip)

GET /api/products?$top=25&$skip=0
GET /api/products?$top=25&$skip=25

Cursor-based with NextLink

NextLink encodes the current query state into a Base64URL $skiptoken and returns it as the next-page cursor. Returns null on the last page.

[HttpGet]
public IActionResult Get(ApiQueryOptions<Product> options)
{
    List<Product> items = _db.Products.Apply(options).ToList();
    int total = _db.Products.Count();

    return Ok(new
    {
        value    = items,
        nextLink = options.NextLink(items.Count, total),  // null when no more pages
    });
}

The client passes the returned cursor as $skiptoken on the next request:

GET /api/products?$skiptoken=<token>

IQueryable extensions

using ApiQueryOptions.Extensions;

IQueryable<T> result = query.Apply(options);            // filter → orderby → skip → top

query = query.ApplyFilter(options.Filter!, settings);
query = query.ApplyOrderBy(options.OrderBy!, settings);
query = query.ApplySkip(options.Skip!, settings);
query = query.ApplyTop(options.Top!, settings);

Configuration (ApiQueryOptionsSettings)

All properties use init-only setters and default to the most permissive values.

When an option is disabled, any matching query key is silently ignored and the corresponding property on ApiQueryOptions<T> will be null.

*ParameterNames lists are tried left-to-right; the first match wins. Custom names are automatically excluded from NextLink query-string passthrough.

Error handling

Manual construction

// From an HttpRequest (minimal API or middleware):
ApiQueryOptions<Product> options = ApiQueryOptions.FromRequest<Product>(request, settings);

// From an HttpContext — safe when context is null (returns empty no-op instance):
ApiQueryOptions<Product> options = ApiQueryOptions.FromRequest<Product>(httpContext, settings);

// From an IHttpContextAccessor (in a service):
ApiQueryOptions<Product> options = ApiQueryOptions.FromRequest<Product>(httpContextAccessor, settings);

// From any IQueryCollection:
ApiQueryOptions<Product> options = new(queryCollection, settings);

Source & examples

Full documentation, runnable examples, and source: github.com/MassiveScale/ApiQueryOptions