Controllers and routes - Neuron Agent API

Start with a controller

Use [Controller] when you want a class to be discovered by RegisterControllers(...), and use [Route] to define its base path.

[Controller]
[Route("/users")]
public sealed class UsersController : ControllerBase
{
    [HttpGet("")]
    public Task<List<UserSummary>> List()
    {
        return Task.FromResult(new List<UserSummary>
        {
            new UserSummary { UserId = "1", DisplayName = "Ada" },
            new UserSummary { UserId = "2", DisplayName = "Linus" }
        });
    }

    [HttpGet("/me")]
    public Task<UserSummary> GetCurrent()
    {
        return Task.FromResult(new UserSummary
        {
            UserId = "me",
            DisplayName = "Current user"
        });
    }

    [HttpGet("/[userId]")]
    public Task<UserSummary> Get(string UserId)
    {
        return Task.FromResult(new UserSummary
        {
            UserId = UserId,
            DisplayName = "Ada"
        });
    }
}

public sealed class UserSummary
{
    public string UserId { get; set; } = string.Empty;
    public string DisplayName { get; set; } = string.Empty;
}

The full routes become:

GET /api/users
GET /api/users/me
GET /api/users/[userId]

Two registration paths

There are two ways to register attributed controllers:

Scan an assembly with RegisterControllers(typeof(UsersController).Assembly)
Register a single controller type with RegisterController<UsersController>()

[Controller] is required for assembly scanning. Direct RegisterController<T>() registration already names the controller type explicitly.

Parent controllers

Use [Controller(Parent = typeof(...))] when a controller should live under another controller’s route prefix. Parent controllers are route containers. The router walks the parent chain, prepends each parent’s [Route], and then appends the child controller route and method route.

[Controller]
[Route("/parking-areas")]
public sealed class ParkingAreasController : ControllerBase
{
    [HttpGet("/")]
    public Task<List<ParkingAreaResponse>> List()
    {
        return Task.FromResult(new List<ParkingAreaResponse>());
    }
}

[Controller(Parent = typeof(ParkingAreasController))]
[Route("/[areaId]")]
public sealed class ParkingAreaController : ControllerBase
{
    [HttpGet("/")]
    public Task<ParkingAreaResponse> Get(Guid AreaId)
    {
        return Task.FromResult(new ParkingAreaResponse { Id = AreaId });
    }
}

[Controller(Parent = typeof(ParkingAreaController))]
[Route("/squares")]
public sealed class ParkingSquaresController : ControllerBase
{
    [HttpGet("/[squareId]")]
    public Task<ParkingSquareResponse> Get(Guid AreaId, Guid SquareId)
    {
        return Task.FromResult(new ParkingSquareResponse
        {
            Id = SquareId,
            ParkingAreaId = AreaId
        });
    }
}

public sealed class ParkingAreaResponse
{
    public Guid Id { get; set; }
}

public sealed class ParkingSquareResponse
{
    public Guid Id { get; set; }
    public Guid ParkingAreaId { get; set; }
}

Those routes become:

GET /api/parking-areas
GET /api/parking-areas/[areaId]
GET /api/parking-areas/[areaId]/squares/[squareId]

Parent route parameters are part of the final route, so child actions can bind them like any other route parameter. In the example above, AreaId comes from the parent route segment and SquareId comes from the child method route. Each type in the parent chain must be a controller with its own [Controller] and [Route]. Parent controllers can have actions of their own, or they can exist mainly to give nested resources a shared route prefix.

Controller-level middleware and authorization are registered on the route path for the controller that declares them. If a parent controller is registered with middleware on /parking-areas, that middleware can run for deeper routes under /parking-areas/... because the request pipeline walks route-tree parents. Declare child-specific middleware or authorization on the child controller when it should only apply to that nested resource.

HTTP method attributes

Use one of these on controller methods:

[HttpGet("...")]
[HttpPost("...")]
[HttpPut("...")]
[HttpPatch("...")]
[HttpDelete("...")]

The controller route and method route are concatenated.

Attribute-routed controllers currently expose GET, POST, PUT, PATCH, and DELETE. If you need a manual OPTIONS endpoint, register it directly on the router with RegisterOptions(...).

Route template segments

users — literal segment
[userId] — named route parameter
* — any single segment

[Controller]
[Route("/projects")]
public sealed class ProjectsController : ControllerBase
{
    [HttpGet("/[projectId]/files/*")]
    public Task<ProjectFileResponse> GetFile(string ProjectId)
    {
        return Task.FromResult(new ProjectFileResponse
        {
            ProjectId = ProjectId
        });
    }
}

public sealed class ProjectFileResponse
{
    public string ProjectId { get; set; } = string.Empty;
}

How parameter matching works

Route placeholder names are matched against method parameter names case-insensitively. [HttpGet("/[userId]")] can bind to string UserId. Path matching is case-sensitive; route placeholder name matching is case-insensitive.

Reusing controller route prefixes

ControllerBase.GetRoute<T>() returns the route prefix declared on a controller type and caches it for reuse.

string ProjectsRoute = ControllerBase.GetRoute<ProjectsController>();

That is useful when you want to compose links or manual subroutes around an attributed controller without hard-coding the same prefix twice.

Controller lifecycle

The router creates a new controller instance per request:

Request-specific state does not leak between requests
ControllerBase.Context always belongs to the current request
Do not access ControllerBase.Context in the constructor

When to omit `[Route]`

If you omit [Route], the controller base path defaults to /. Most real applications are easier to read when each controller owns a clear path prefix.

What to read next

Binding and responses shows how route values, query strings, and JSON bodies are turned into controller method arguments.

​Start with a controller

​Two registration paths

​Parent controllers

​HTTP method attributes

​Route template segments

​How parameter matching works

​Reusing controller route prefixes

​Controller lifecycle

​When to omit [Route]

​What to read next

Start with a controller

Two registration paths

Parent controllers

HTTP method attributes

Route template segments

How parameter matching works

Reusing controller route prefixes

Controller lifecycle

When to omit `[Route]`

What to read next