Functions.Worker.AddOns.MiniApiRouting 1.0.0

Functions.Worker.AddOns.MiniApiRouting

Compile-time generated Mini APIs for Azure Functions isolated worker.

Overview

MiniApiRouting lets one Azure Function host a logical group of HTTP routes while keeping the isolated-worker programming model. Route handlers are ordinary methods discovered by a source generator and dispatched by generated code.

Why this package exists

A logical API often needs several routes but one authorization boundary. Creating one Function per route forces consumers to manage several equivalent function keys or move to broader host-level keys. MiniApiRouting allows related routes to share one Function, one authorization level, and one function key.

Goals

• Preserve Azure Functions isolated-worker hosting, middleware, DI, authorization, and keys.
• Support default and named Mini APIs in the same app.
• Generate routing, binding, dispatch, and DI registration at compile time.
• Avoid manual switches, dictionaries, runtime discovery, reflection, or assembly scanning.

Non-goals

MiniApiRouting is not MVC, controllers, MediatR, pipeline behaviors, output serialization, automatic HTTP error responses, form-data binding, cookie binding, or arbitrary body-format binding.

Compile-time advantages

The generator validates route handlers, ambiguous routes, optional path rules, binding conflicts, body parameters, route templates, and Function-to-Mini-API associations before runtime.

Supported frameworks

• Runtime: net8.0, net10.0
• Source generator: netstandard2.0

Installation

dotnet add package Functions.Worker.AddOns.MiniApiRouting

The package includes the runtime library and generator analyzer. Consumers install only this package.

Registration

builder.Services.AddFunctionsMiniApiRouting();

The generated extension registers route handler classes with TryAddTransient, IMiniApiRouter with TryAddSingleton, and IMiniApiRequestBodyDeserializer with TryAddSingleton.

Async-first Widget API example

internal static class MiniApis
{
    internal const string Widgets = "widgets";
}

[MiniApi(MiniApis.Widgets)]
internal sealed class WidgetRouteHandlers(IWidgetService widgetService)
{
    [MiniApiRouteHandler(MiniApiVerbs.Get, "/{widgetId:int}")]
    public Task<WidgetDto?> GetWidgetAsync(int widgetId, string? include = null, CancellationToken cancellationToken = default)
        => widgetService.GetWidgetAsync(widgetId, include, cancellationToken);

    [MiniApiRouteHandler(MiniApiVerbs.Post)]
    public Task<WidgetDto> CreateWidgetAsync(CreateWidgetRequest request, CancellationToken cancellationToken)
        => widgetService.CreateWidgetAsync(request, cancellationToken);
}

Default Mini API example

Use [MiniApi] and [MiniApiFunction] without a name for the default group.

Named Mini API example

Use constants with [MiniApi(MiniApis.Widgets)] and [MiniApiFunction(MiniApis.Widgets)]. Group names are never inferred from class names.

Multiple Mini APIs and Functions example

Several classes can contribute handlers to the same group, and several Functions can host different groups in one app.

Function delegation

internal sealed class WidgetFunction(IMiniApiRouter router)
{
    [Function(nameof(WidgetFunction))]
    [MiniApiFunction(MiniApis.Widgets)]
    public ValueTask<object?> RunAsync(HttpRequestData request, string? path, CancellationToken cancellationToken)
        => router.DispatchAsync(request, path, cancellationToken);
}

The generated router resolves the Mini API group from the current Function name and MiniApiFunctionAttribute.

Route parameter binding

Scalar parameters matching route tokens bind from route values and take precedence over query strings.

Query-string and repeated collection binding

Scalar query parameters bind from HttpRequestData.Query. Repeated values support arrays, List<T>, IList<T>, IReadOnlyList<T>, IEnumerable<T>, ICollection<T>, and IReadOnlyCollection<T> for supported scalar element types. Scalar parameters use the first value deterministically.

Explicit header binding

Headers require [MiniApiFromHeader("x-correlation-id")] and are not bound by convention.

Inferred and explicit body binding

One complex parameter binds from the JSON body automatically. Use [MiniApiFromBody] to opt in explicitly.

Custom IMiniApiRequestBodyDeserializer example

Register a custom IMiniApiRequestBodyDeserializer before AddFunctionsMiniApiRouting to support XML or another format. The default package ships JSON support only and uses the Azure Functions worker-configured ObjectSerializer.

Route priority and natural specificity

MiniApiRouteHandlerAttribute.Priority defaults to 100. Lower values run first. Ties prefer static segments, constrained parameters, unconstrained parameters, then catch-all parameters.

Catch-all route example

[MiniApiRouteHandler(MiniApiVerbs.Get, "/assets/{*path}")]
public Task<DigitalAsset?> GetAssetAsync(string path, CancellationToken cancellationToken)
    => assets.GetAsync(path, cancellationToken);

Catch-all parameters must be terminal.

Optional trailing path parameters

Nullable or defaulted trailing route parameters are optional. Optional route parameters must be contiguous and trailing.

Supported return shapes

Handlers may return T, Task<T>, ValueTask<T>, void, Task, or ValueTask. Results are not serialized or converted by MiniApiRouting.

Exception handling

Routing and binding failures throw MiniApiRouteNotFoundException, MiniApiParameterBindingException, or MiniApiUnsupportedContentTypeException. The library does not create HTTP error responses.

Compile-time diagnostic table

Package architecture

The NuGet package contains runtime assemblies under lib/net8.0 and lib/net10.0 plus the generator under analyzers/dotnet/cs.

Contributing and validation commands

dotnet restore
dotnet build -c Release
dotnet test -c Release --no-build
dotnet pack -c Release --no-build

Current release status

Preview implementation under active validation.