Skip to main content

Getting started

From package to bounded query endpoint.

Install ServiceQuery®, build a structured request, execute it over the queryable source your API owns, and expose the result through an endpoint you control.

Flexible queries. Deliberate boundaries.

Install the foundation

Add the package to the API you already own.

Choose the installation path that fits your .NET workflow, then continue to the request model.

.NET CLI

dotnet add package ServiceQuery

Package Manager

Install-Package ServiceQuery

PackageReference

<PackageReference Include="ServiceQuery" />

Provider-Specific Installation

Choose the package for the data source you use.

The default ServiceQuery® library provides synchronous support. Add a provider-specific package when your data source needs additional integration or asynchronous execution.

ServiceQuery

The default library provides synchronous query support.

ServiceQuery.AzureDataTables

Provides support for Azure storage accounts and their data tables.

ServiceQuery.EntityFrameworkCore

Provides async support. Note: .NET Core 8 uses the EFC 9 package.

ServiceQuery.EntityFrameworkCore8

Provides async support for .NET Core 8 using EFC 8. This custom package exists because of the EFC 8 and EFC 9 distinction.

ServiceQuery.MongoDb

Provides synchronous and asynchronous support for MongoDB databases.

Build the request

Describe the query as data, not another endpoint convention.

The fluent builder adds ordered filters and operations to a ServiceQueryRequest. Build only the operations your API has decided to expose.

A first C# request

using ServiceQuery;

var request = new ServiceQueryRequestBuilder()
    .IsEqual("Status", "Active")
    .SortDesc("CreatedAt")
    .Paging(1, 25, true)
    .Build();

What the request contains

  • A comparison for the fields the client is allowed to query.
  • A descending sort on a field the API permits.
  • Page number and page size chosen within server limits.
  • An explicit request for total-count metadata.

The builder creates the request model. The API still decides whether the requested fields, operations, scope, and limits are valid.

Execute against your source

Let the API choose the queryable source.

ServiceQuery® executes the structured request over the IQueryable source selected by the API. Provider translation and supported expression behavior remain contextual.

Synchronous execution

var queryable = databaseContext.Products
    .AsQueryable();

var response = request.Execute(queryable);

Asynchronous execution

var queryable = databaseContext.Products
    .AsQueryable();

var responseAsync = await request
    .ExecuteAsync(queryable);

Put it behind an API boundary

Execute the request inside the scope your server owns.

A dynamic request does not replace authentication, authorization, tenant scope, field policy, or operational limits. Establish those boundaries before execution. The examples below abbreviate how authenticated tenant context is resolved.

Minimal API boundary (abbreviated)

app.MapPost("/products/query",
    (ServiceQueryRequest request, AppDb db) =>
{
    // tenantId comes from authenticated request context.
    var scopedProducts = db.Products
        .Where(product => product.TenantId == tenantId)
        .Where(product => !product.IsDeleted);

    return Results.Ok(request.Execute(scopedProducts));
});

Controller boundary (abbreviated)

[HttpPost("query")]
public ServiceQueryResponse<Product> Query(
    ServiceQueryRequest request)
{
    var scopedProducts = _db.Products
        .Where(product => product.TenantId == _tenantId);

    return request.Execute(scopedProducts);
}

Use the same model from JavaScript

Send structured query intent from a browser client.

The JavaScript builder produces the same request shape for an HTTP endpoint. Keep the server as the authority over what that request may do.

JavaScript builder

const request = new ServiceQueryRequestBuilder()
    .IsEqual("Status", "Active")
    .SortDesc("CreatedAt")
    .Paging(1, 25, true)
    .Build();

HTTP request

fetch('/api/products/query', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(request)
});

Inspect. Run. Adopt.

Your API owns the boundary. ServiceQuery® supplies the query path.

Review the operation surface, run a real request, and apply the pattern where structured querying helps the API you already have.