UKBatch.Api 0.2.2-alpha

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher.
This is a prerelease version of UKBatch.Api. 
dotnet add package UKBatch.Api --version 0.2.2-alpha
                    


                    

                
NuGet\Install-Package UKBatch.Api -Version 0.2.2-alpha
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="UKBatch.Api" Version="0.2.2-alpha" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="UKBatch.Api" Version="0.2.2-alpha" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="UKBatch.Api" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add UKBatch.Api --version 0.2.2-alpha
                    


                    

                
#r "nuget: UKBatch.Api, 0.2.2-alpha"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package UKBatch.Api@0.2.2-alpha
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=UKBatch.Api&version=0.2.2-alpha&prerelease
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=UKBatch.Api&version=0.2.2-alpha&prerelease
                    


                            Install as a Cake Tool

UKBatch.Api

REST endpoints, an OpenAPI document, and a SignalR push hub for UKBatch — a lightweight, pluggable batch/job orchestration library for .NET 8 and .NET 10. It mounts onto any RouteGroupBuilder in an ASP.NET Core app and is auth-agnostic: anonymous by default, opt-in via RequireAuthorization. The hub broadcasts execution, progress, approval, and batch-completion events for dashboard clients.

Status: part of the UKBatch 0.1.0-alpha package family.

Install

dotnet add package UKBatch.Api

UKBatch.Api brings UKBatch.AspNetCore, UKBatch.Core, and UKBatch.Abstractions transitively.

Quick start

using UKBatch.Api;
using UKBatch.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.AddUKBatchAspNetCore(b => b.AddJob<MyJob>());
builder.Services.AddUKBatchApi();

var app = builder.Build();

app.MapGroup("/api").MapUKBatchApi();   // REST + SignalR hub
app.MapOpenApi();                       // /openapi/v1.json — .NET 9+ only; omit on .NET 8

app.Run();

Trigger a job: curl -X POST http://localhost:5050/api/jobs/MyJob/trigger -H "Content-Type: application/json" -d '{}'.

A full demonstration lives under samples/Sample.RestApi.

REST surface

The main route groups (mounted under whatever prefix you map):

Group Examples
Jobs GET /jobs, GET /jobs/{name}, POST /jobs/{name}/trigger
Batches (definitions) GET /batches, GET /batches/by-name/{name}, POST /batches, PUT/DELETE /batches/by-id/{id}
Batch runs POST /batches/by-name/{name}/run, GET /batches/{batchRunId}/status
Executions GET /executions/{id}, POST /executions/query, POST /executions/{id}/cancel
Approvals GET /approvals, POST /approvals/{id}/approve, POST /approvals/{id}/reject
Workers GET /workers (server + workers deployment registry)

The complete surface — every route, request/response schema, and the ProblemDetails error map — is in the generated OpenAPI document at /openapi/v1.json (wired automatically by AddUKBatchApi(); default transformers annotate operations with 400/403/404/409/500 responses and render enums as strings).

.NET 8 note: built-in OpenAPI document generation requires .NET 9+. On the net8.0 target every endpoint and the SignalR hub behave identically (including enum-as-string JSON), but /openapi/v1.json is not produced — layer Swashbuckle over the mapped endpoints if you need a document on .NET 8.

SignalR hub

The hub lives at /hubs/jobs (relative to the map prefix; configurable via UKBatchOptions.HubPath). Clients subscribe with SubscribeToExecution / SubscribeToBatch / SubscribeToJob / SubscribeAll and receive ExecutionStateChanged, ProgressUpdated, ApprovalRequested, and BatchCompleted.

Two client contracts matter:

  • Dedupe events. A client subscribed to several matching groups receives each event once per group (up to 4 copies). Dedupe by (ExecutionId, Status, AttemptNumber) for executions and by (BatchId, FinalStatus) for batch completion.
  • Re-subscribe after reconnect. SignalR loses group memberships on reconnect; re-subscribe to active groups when Reconnected fires.

Authorization

Auth-off by default. Opt in at the route group, or mount the same surface twice — anonymous and secured:

app.MapGroup("/api").MapUKBatchApi();                    // anonymous
app.MapGroup("/api/secured")
   .MapUKBatchApi("Secured")                             // operationId prefix avoids OpenAPI collisions
   .RequireAuthorization();

Approver identity is derived exclusively from HttpContext.User — the request body never contributes identity or roles. UKBatchOptions.ApprovalRoleClaimTypes selects which claim type(s) to scan (default [ClaimTypes.Role]; configure extras via appsettings.json for Azure AD / Auth0 / SAML).

Critical notes

  • The default stores are in-memory — all state is process-local and resets on restart. Add UKBatch.Storage.EntityFrameworkCore for persistence (register it after AddUKBatchApi).
  • Errors are returned as RFC 9457 ProblemDetails with stable ukbatch:* type URIs (e.g. ukbatch:job-not-registered, ukbatch:execution-not-found).
  • Useful UKBatchOptions — runtime: MaxDegreeOfParallelism, DispatcherChannelCapacity, DefaultMaxRetries; API surface: HubPath, HubBufferCapacity, DefaultPageLimit / MaxPageLimit, MaxQueryStatusesCount, ApprovalRoleClaimTypes.

When to use it

Add this package when you want a REST surface and live status push over your UKBatch runtime — for an API client, the bundled dashboard, or a server + workers deployment. If you only need to run jobs in-process with no HTTP surface, UKBatch.AspNetCore (or UKBatch.Core) is enough.

License

MIT. See LICENSE in the repo root. Full docs: nspukcode-hub.github.io/UKBatch · GitHub.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on UKBatch.Api:

Package Downloads
UKBatch.Dashboard

Blazor Server centralized dashboard for UKBatch services — monitoring, triggering, approvals, and a visual batch editor. Multi-service via IUKBatchServiceRegistry; subscribes to REST + SignalR endpoints exposed by UKBatch.Api.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.2.2-alpha 64 6/18/2026
0.2.1-alpha 61 6/15/2026
0.2.0-alpha 59 6/14/2026
0.1.6-alpha 60 6/13/2026
0.1.5-alpha 61 6/12/2026
0.1.4-alpha 59 6/10/2026
0.1.3-alpha 62 6/8/2026
0.1.1-alpha 62 6/8/2026
0.1.0-alpha 58 6/6/2026

See https://github.com/nspukcode-hub/UKBatch/blob/main/CHANGELOG.md