> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Neuron HTTP router

> Learn the Neuro.Networking.HttpRouter package from setup to advanced request handling

## Overview

`Neuro.Networking.HttpRouter` supports two complementary styles:

* Manual endpoint registration with `RegisterGet`, `RegisterPost`, `RegisterPut`, `RegisterPatch`, `RegisterDelete`, and `RegisterOptions`
* Attribute-based controllers with per-request controller instances, binding, validation, staged middleware, and automatic JSON responses

This guide starts with the controller model because it is the package's intended high-level API, but the same router also exposes lower-level primitives when you need direct control.

<Note>
  The main package documented here is `Neuro.Networking.HttpRouter`. Controller-based APIs also use types from `Neuro.Networking.HttpRouter.Core`, and OpenAPI generation uses the companion `Neuro.Networking.HttpRouter.OpenApi` assembly.
</Note>

## Install the package

```bash theme={null}
dotnet add package Neuro.Networking.HttpRouter
```

or:

```xml theme={null}
<ItemGroup>
  <PackageReference Include="Neuro.Networking.HttpRouter" />
</ItemGroup>
```

## Minimal setup

Create a `ControllerEndpointRouter`, register it with your HTTP server, and then either scan an assembly or register one controller directly.

```csharp theme={null}
using Neuro.Networking.HttpRouter;
using Neuro.Networking.HttpRouter.Core;
using Waher.Networking.HTTP;

HttpServer Server = new HttpServer(8080);
ControllerEndpointRouter Router = new ControllerEndpointRouter(
    "/api",
    true,
    new CamelCaseParameterNameCodec());

Server.Register(Router);
Router.RegisterControllers(typeof(UsersController).Assembly);

// Or register a single controller explicitly:
// Router.RegisterController<UsersController>();
```

With that setup, a controller route like `/users` becomes available under `/api/users`.

## Current feature surface

The current router surface includes:

* Per-request controller instances and constructor injection through `Router.ServiceProvider`
* Transport validation on bound parameters and body models
* A staged middleware pipeline from `Infrastructure` through `PostHandler`
* Router-level authentication scheme registration through `UseAuthenticationScheme(...)`
* Configurable JSON field naming through the router's `IParameterNameCodec`
* OpenAPI document generation from the registered route tree

## A first mental model

When a request hits the router:

1. Matches the HTTP method and path
2. Runs any middleware registered for that route and stage
3. Creates a controller instance for the request
4. Binds route, query, and body values to method parameters and validates them
5. Calls the controller action
6. Serializes the returned object to JSON unless the action is raw

## First example

```csharp theme={null}
[Controller]
[Route("/users")]
public sealed class UsersController : ControllerBase
{
    [HttpGet("/[userId]")]
    public Task<UserResponse> Get(string UserId)
    {
        return Task.FromResult(new UserResponse
        {
            UserId = UserId,
            DisplayName = "Ada"
        });
    }
}

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

A `GET` request to `/api/users/42` returns JSON based on the `UserResponse` object.

## A good default order

Register middleware before calling `RegisterControllers(...)` if you want it to run in front of your controllers.

```csharp theme={null}
ControllerEndpointRouter Router = new ControllerEndpointRouter(
    "/api",
    true,
    new CamelCaseParameterNameCodec());

Router.RegisterMiddleware("/users/*", (HttpContext Context, Action<HttpContext> Next) =>
{
    Next(Context);
    return Task.CompletedTask;
});

Router.RegisterControllers(typeof(UsersController).Assembly);
```

## Router-level authentication helpers

The router can also advertise authentication schemes for the endpoints it serves.

```csharp theme={null}
ControllerEndpointRouter Router = new ControllerEndpointRouter(
    "/api",
    true,
    new CamelCaseParameterNameCodec());

Router.UseAuthenticationScheme(HttpAuthenticationSchemes.GetAccountsAuthenticationScheme());
Router.UseAuthenticationScheme(HttpAuthenticationSchemes.GetLegalSignatureScheme());
Router.UseAuthenticationScheme(HttpAuthenticationSchemes.GetAnonymousScheme());
```

Call `UseAuthenticationScheme(...)` with a custom `HttpAuthenticationScheme` when the built-in account, legal-signature, or anonymous schemes are not enough.

## OpenAPI document generation

The `Neuro.Networking.HttpRouter.OpenApi` companion assembly can generate an OpenAPI document from the routes registered on a `ControllerEndpointRouter`.

The generator returns the typed `OpenApiDocument` model from [Neuro.Content.OpenApi](/neuron-development/first-party-packages/neuron-content-openapi), which also provides the JSON content codec used when the document is returned over HTTP.

Parklet exposes this as a normal endpoint:

```csharp theme={null}
using Neuro.Content.OpenApi.Model;
using Neuro.Networking.HttpRouter;
using Neuro.Networking.HttpRouter.Core;
using Neuro.Networking.HttpRouter.OpenApi;

public sealed class ParkletHttpService
{
    public ParkletHttpService(ControllerEndpointRouter Router)
    {
        Router.RegisterGet("/open-api", async (ExtendedHttpRequest Req, HttpResponse Res) =>
        {
            OpenApiDocument Document = OpenApiGenerator.Generate(
                Router,
                new OpenApiInfo
                {
                    Title = "Parklet API",
                    Version = "3.0.0"
                });

            Document.Servers.AddRange(OpenApiGenerator.CurrentServers());
            await Res.Return(Document);
        });

        Router.RegisterControllers(typeof(ParkletHttpService).Assembly);
    }
}
```

The generator reads the router's route tree and emits an OpenAPI `3.0.3` document. It infers paths, route parameters, query parameters, request bodies, response schemas, and security metadata from registered controllers and manual endpoints. It also uses the active `IParameterNameCodec`, so a router configured with `SnakeCaseParameterNameCodec` produces snake-case JSON schema fields.

Use `[Summary]`, `[Description]`, and `[Tag]` from `Neuro.Networking.HttpRouter.OpenApi` to improve operation text and grouping in generated docs.

## What to read next

* [Controllers and routes](/neuron-development/first-party-packages/neuron-http-router/controllers-and-routes)
* [Binding and responses](/neuron-development/first-party-packages/neuron-http-router/binding-and-responses)
* [Middleware and pipeline](/neuron-development/first-party-packages/neuron-http-router/middleware-and-pipeline)
* [Authorization](/neuron-development/first-party-packages/neuron-http-router/authorization)
* [Advanced patterns](/neuron-development/first-party-packages/neuron-http-router/advanced-patterns)
* [Neuro.Content.OpenApi](/neuron-development/first-party-packages/neuron-content-openapi)
* [Release notes](/neuron-development/first-party-packages/neuron-http-router/release-notes)