Skip to main content

Nexus HTTP API

A REST API for all Nexus features are included, and it's what the admin UI uses. The API is not enabled by default but all you need to do to enable it is:

builder.Services.AddNexus().AddApi(options =>
{
    // The default options are:
    options.BasePath = "/";
    options.RegisterHealthChecksAsAspNetCoreHealthChecks = true;
    options.AllowAnonymousApiAccess = true;
});

When BasePath is / it means that the API is accessible on https://servername/api and if you set it to /mybasepath/ the API is accessible on https://servername/mybasepath/api.

BasePath no longer configures the separately packaged Admin UI. When hosting them together, pass the same value to NexusAdminUIOptions.ApiBaseUrl; see the Admin UI documentation.

Authentication​

One of the options above is if the system should allow anonymous API access or not. If you configure the API not to allow it the system does not do any authorization though and leaves it up to you to authorize the user through eg a cookie (see more about authorization below). The system will check if HttpContext.User.Identity.IsAuthenticated and otherwise respond with HTTP status 401 on any API requests.

If you wish to add login to the Admin UI you should setup a middleware on the admin route which checks if the user is signed in or not and redirect to/display a login page. Something like this:

// Program.cs
builder.Services.AddNexus()
    .AddApi(options => options.AllowAnonymousApiAccess = false)
    .AddAdminUI(options => options.ApiBaseUrl = "/");

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.Use(async (context, next) =>
{
    if (context.Request.Path.StartsWithSegments("/nexus") && context.User.Identity?.IsAuthenticated != true)
    {
        context.Response.Redirect("/login");
        await context.Response.CompleteAsync();
    }
    else
    {
        await next();
    }
});
app.UseNexusAdminUI();

If you then implement the /login route to show a login form that redirects back to /nexus when the user has logged in your Nexus admin UI and API is fully protected.

Authorization​

Nexus offers a very granular level of authorization on endpoints that perform update/create/delete actions. When initializing the Nexus API you can pass an async lamda to authorize an HTTP request like this:

// Program.cs
builder.Services.AddNexus().AddApi(options =>
{
    options.IsReadOnly = async (httpContext, nexusEndpoint) =>
    {
        if (nexusEndpoint == NexusEndpoint.DeleteAllQueueItems)
        {
            var user = await httpContext.RequestServices.GetRequiredService<IUserService>().GetCurrentUserAsync();
            // Only allow admins to nuke all queue items
            return !user.IsAdmin;
        }
        return false;
    };
});

The NexusEndpoint class contains all endpoints that the Nexus API contains which mutates anything. If you want to build a dynamic registry of which users are allowed to use which endpoints you can use the NexusEndpoint.AllNexusEndpoints list to base it on. The list is generated and the static name of an endpoint is the same as the static name. That is, this will always be true:

nameof(NexusEndpoint.Xyz) == NexusEndpoint.Xyz.Name

The implementation here is of course made up and your implementation would look differently. Any update/create/delete request sent to the API where the IsReadOnly lambda returns true will fail with a 403 status.

Note that the admin UI will still display all editing controls but will fail with an error message if a user tries to do something unauthorized.

List responses and identities​

GET /api/jobs returns { "jobs": [...], "categories": [...] }. There is no separate GET /api/jobs/categories endpoint. A queue job's schedule can be null; use its activation/waiting state rather than assuming it always has a next cron run.

GET /api/queues omits counts by default. Pass queueNamesWithCounts for selected queues or includeCountsForAll=true to request all counts. Missing counts mean not loaded, not zero. Historical job runs are identified by correlationId; extra-run IDs are 64-bit integers. Custom clients must also recognize AwaitingRelease and statusAfterRelease.

The start endpoint follows IJobStartRequester: an immediate request with no parameters can be best-effort. Specify an explicit UTC startAt to persist an extra run, or use IJobMetaDataRepository.ScheduleExtraRunAsync() in application code. See job starts.

Queue creation payloads no longer have startProcessing. Ready messages follow the queue's configured processing mode. Processing settings and distributed-processor status/pause controls are available on queue-specific endpoints.

Feature discovery​

GET /api/enabled-features reports the API host's configured features and is served by the API package. A separately hosted Admin UI uses this endpoint on its configured API base URL. Menu customization belongs to the UI host's MenuItemsLoader.

Endpoints​

Besides the NexusEndpoint class for mutative endpoints you can see a full list of the API endpoints for the Nexus API in the API reference.

The OpenAPI JSON document is also available for client generation.

Nexus also has an optional MCP HTTP server for agents and tools. See Nexus MCP for setup and available tool groups.

There's a demo environment that's deployed to a free tier Azure Web App here:
https://commerce-mind-nexus-a9bsbwgth3cgfnde.swedencentral-01.azurewebsites.net/swagger/index.html

You can send requests to any endpoint you'd like to get a feel for what the system does. Since it's a free tier Azure Web App the scheduler is paused when nobody is using the API or admin UI which means that the jobs won't run exactly according to schedule.