Controllers & routes
Controllers as plain structs, routes from #[routes], path/query/JSON extractors, typed returns — the minimum to ship an HTTP handler.
A controller is a plain struct: inject what it needs, hang verb methods
off its impl block, and #[routes] generates the route table. Verb
attributes (#[get], #[post], #[put], #[delete], #[patch]) bind a
method to a path, and #[sse] binds a GET that
answers an event stream. Extractors, validation and response types all live in
nest_rs::http, beside the DI shape and the self-composing route table.
This page covers the minimum to ship an HTTP handler. Response shaping (responses), error mapping (errors), the extractor surface (extractors) and URI versioning (versioning) each have their own page.
The minimal controller
Section titled “The minimal controller”use std::sync::Arc;
use nest_rs::http::{controller, routes};
use crate::hello::HelloService;
#[controller(path = "/")]pub struct HelloController { #[inject] svc: Arc<HelloService>,}
#[routes]impl HelloController { #[get("/")] #[public] async fn hello(&self) -> String { self.svc.greeting() }}-
#[controller(path = "/")]mounts the impl block under that path. -
#[inject] svc: Arc<HelloService>declares a dependency — the container hands the controller the sharedArc<HelloService>when it builds the controller. -
#[routes]generates the route table; one entry per verb attribute. -
#[public]declares the route open on purpose. A route with neither a guard nor#[public]refuses the boot, which names every such route — see Security. -
async fn hello(&self) -> String— any type that implementsIntoResponseis a valid return.String,&'static str,Json<T>,StatusCode,(StatusCode, Body), a builtResponse… all work, and so does aResultof any of them. -
A controller is built as an
#[injectable]provider is. Its#[inject]fields resolve from the container; a struct with no field at all is built as written, and one whose fields are all plain falls back to its ownDefault, which rustc names when it is missing:crates/features/src/greetings/http/controller.rs #[controller(path = "/greetings")]pub struct GreetingsController;
Run it:
$ nestrs run dev…2026-06-03T10:14:22Z INFO nest_rs::routes: mounted host="HelloController" method="hello" verb="GET" path="/"
$ curl http://localhost:3000Hello WorldThe boot line is authoritative about the served path. One
nest_rs::routes: mounted event per route — its host the controller, its
method the handler, its verb the HTTP method — with the full path in the
path field: the transport logs what it actually mounted, prefix and version
folded in. Every edge says a unit it serves the same way, so one filter on
mounted lists what the binary serves.
#[get("/")] on #[controller(path = "/greetings")] serves /greetings, and
/greetings/ reaches the same handler: the transport edge trims the trailing
slash before anything routes on the path, so both spellings run the same
guards, interceptors and exception filters. The mounted path — the one the
event above prints, the one the OpenAPI document lists — is the trimmed form.
Interior slashes are left alone: /greetings//hello is a different path, not a
typo.
When a route seems missing, compare your URL against the path field of that
event rather than against the attribute.
Adding a path parameter
Section titled “Adding a path parameter”use nest_rs::http::Path;
#[get("/{name}")]#[public]async fn greet(&self, Path(name): Path<String>) -> String { format!("Hello, {name}!")}Path<T> extracts a typed path segment. Typed parsing fails with 400
before the handler runs — there is no name.parse::<i32>() to handle
manually.
Destructuring in the parameter list is supported — Path(name),
Query(q), Json(body), Piped(id) — as long as the pattern binds one
name. #[routes] forwards the argument to the handler it generates under that
name, so the pattern stays where you wrote it. A pattern binding two
(Path((a, b))) has no single name to forward and is a compile error naming
the way out: bind the whole extractor and destructure in the body.
A handler reading another number of path parameters than its route declares
answers 500 and files a handler reads path parameters its route cannot bind,
its error field counting both; bind every parameter, or read them through a
struct.
$ curl http://localhost:3000/AdaHello, Ada!Route templates
Section titled “Route templates”A route’s path is written in OpenAPI’s path templating, the spelling the
OpenAPI document already prints: what you write in the attribute is
what the document, the span’s http.route and the
rate limiter’s bucket all read back, /users/{id} everywhere.
| Template | Matches | Binds |
|---|---|---|
/users/{id} | /users/42 | id = 42 |
/@{handle} | /@ada — a parameter may follow literal text in its segment | handle = ada |
/files/{*path} | /files/a/b.txt — the rest of the path | path = a/b.txt |
/{{raw}} | /{raw} — a doubled brace is a literal one | nothing |
A parameter reads up to the next /, so it ends its segment; a catch-all takes
the rest of the path, so it comes last. Neither matches an empty value:
/a//b reaches no /a/{x}/b, and a root catch-all /{*path} leaves / to a
route of its own — declare #[get("/")] beside it, or / answers the
fallback’s 404. Each value is percent-decoded once, so a %2F is a / inside
it; one whose bytes are not UTF-8 is a 400 naming the parameter, never its
value. A controller’s own path may hold parameters too (/orgs/{org}/members);
it ends before its routes, so it holds no catch-all.
Everything else is refused at compile time, at the literal, with the spelling to write instead:
error: #[get] `/users/:id`: `:id` is the 6.x parameter syntax — write `/users/{id}`error: #[get] `/files/*rest`: `*rest` is the 6.x catch-all syntax — write `/files/{*rest}`error: #[get] `/{id:\d+}`: a route parameter carries no pattern — parse it with its type (`Path<u64>`) or a pipeerror: #[get] `/{id}.json`: `{id}` ends its segment — a parameter reads up to the next `/`error: #[get] `/{*rest}/meta`: `{*rest}` comes last — a catch-all takes the rest of the pathA parameter carries no pattern because its type already is one: Path<u64>
answers 400 for /users/abc before the handler runs, and a
pipe says why in a sentence of its own. Two spellings of
one address — /{id} on one handler and /{key} on another — are one route
with two names for its parameter, refused at compile time inside a controller
and at boot across two, naming both handlers.
Reading query parameters
Section titled “Reading query parameters”use nest_rs::http::Query;use nest_rs::core::input;
#[input]struct Greet { lang: Option<String>,}
#[get("/")]#[public]async fn hello(&self, Query(q): Query<Greet>) -> String { match q.lang.as_deref() { Some("fr") => "Bonjour le monde".to_string(), _ => self.svc.greeting(), }}$ curl 'http://localhost:3000/?lang=fr'Bonjour le mondeAccepting a JSON body, validated
Section titled “Accepting a JSON body, validated”use nest_rs::core::{input, output};use nest_rs::http::{Json, Result};
#[input]struct GreetInput { #[validate(length(min = 1))] name: String,}
#[output]struct GreetReply { greeting: String,}
#[post("/")]#[public]async fn shout(&self, Json(input): Json<GreetInput>) -> Result<Json<GreetReply>> { Ok(Json(GreetReply { greeting: format!("HELLO, {}!", input.name.to_uppercase()), }))}#[input]is the shorthand for a DTO the edge decodes. It derivesSerialize,Deserialize,ValidateandJsonSchemathrough the framework, so your manifest names none of those crates, and adds#[serde(deny_unknown_fields)]— an unknown field on the wire ({"name":"Ada","is_admin":true}) is rejected with400at parse time instead of silently dropped. Don’t top the list up by hand — a manual#[derive(Serialize)],#[derive(Deserialize)]or#[derive(Validate)]next to#[input]is a conflicting impl (E0119), not an addition. Need a customDeserializeshape (e.g. untagged enums)? Skip#[input]and derive all four by hand.#[output]is its twin for a DTO the edge only sends, such asGreetReply:SerializeandJsonSchema, nothing to decode or validate. An enum both decoded and sent, a role a client names and reads back, takes#[wire_enum].Json<T>parses the request body intoT. A body that does not decode is400, and itsdetailsays where, in the namesTdeclares, what kind of value it found and what was expected —JSON body at `author.name`: invalid type: an integer, expected a string, an element asitems[2]— and never the value refused, nor a key the client sent: serde’s own sentence quotes both, and a body field is where a password or a card number travels. A map’s entry is said aslimits[…], since its key is the client’s. A body that is not JSON at all keeps its line and column instead. A body sent under another media type is415, naming the type it expected and never the one sent.Form<T>(form field `grant_type`: missing),Query<T>(query parameter `file`: a value its type does not accept, expected a formatted UUID string),Path<T>andHeader<T>refuse the same way, and so does a handler’s own decode returned as a400(HttpError::new(err, StatusCode::BAD_REQUEST)).- The rules
GreetInputdeclares run on the extracted value, after the guards and before the handler, with nothing to wrap: a failure returns400with the structured error list — no manual checks in the handler. A transform other than validation is a pipe,Piped<P, E>, covered in extractors.
$ curl -sX POST http://localhost:3000/ \ -H 'Content-Type: application/json' \ -d '{"name":"ada"}'{"greeting":"HELLO, ADA!"}
$ curl -sX POST http://localhost:3000/ \ -H 'Content-Type: application/json' \ -d '{"name":""}'{"type":"about:blank","title":"Bad Request", "status":400,"detail":"validation failed","code":"INVALID_ARGUMENT", "errors":{"name":[{"code":"length"}]}}Returning typed JSON
Section titled “Returning typed JSON”Json<T> works as a return type as well — the framework serializes T
and sets Content-Type: application/json; charset=utf-8:
#[get("/me")]#[public]async fn me(&self) -> Json<GreetReply> { Json(GreetReply { greeting: self.svc.greeting() })}That single type drives three things in lockstep: the wire format, the
OpenAPI schema (via schemars::JsonSchema on T), and the response body.
None of them can drift from the others — they share one source.
Need a different status, a redirect, a custom header? See
responses for the response-shaping attributes that
sit beside the verb. Need the handler’s Err(...) to render a structured
JSON body? See errors for ToProblem and
ProblemDetails.
Going further
Section titled “Going further”- Responses —
Json<T>, status + body tuples, and how several shapers compose. - Extractors — the full extractor surface a handler parameter can take.
- Errors —
ToProblemon a feature error enum, and RFC 9457 problem responses. - Security — binding a guard so the handler runs with a principal and an ambient ability.