Request Data

Minimal API handlers can receive the current mach::Context& to access data associated with the request.

The context exposes the Request through context.request:

app.mapGet("/users/{id:int}", [](mach::Context& context) {
    const int id = context.request.routeParam<int>("id");
    return mach::ok(id);
});

If a handler does not need request or response data, it does not need to accept a context parameter.

Request Metadata

The request exposes information about the incoming HTTP message:

const auto method = context.request.method();
const auto version = context.request.version();
const auto target = context.request.target();

method() returns the HTTP method.
version() returns the HTTP version.
target() returns the request target.

The raw request body is also available through:

const auto& body = context.request.body();

For structured request bodies, prefer the body-handling APIs covered in the next guide.

Route Parameters

Route parameters are accessed with routeParam():

app.mapGet("/users/{id:int}", [](mach::Context& context) {
    const int id = context.request.routeParam<int>("id");
    return mach::ok(id);
});

String parameters do not require an explicit template argument:

app.mapGet("/users/{name}", [](mach::Context& context) {
    const auto name = context.request.routeParam("name");
    return mach::ok(name);
});

Route patterns and constraints are covered in detail in the Routing guides.

Query Parameters

Use query() to access query parameters.

For example:

app.mapGet("/search", [](mach::Context& context) {
    const auto query = context.request.query("q");

    if (!query) {
        return mach::badRequest();
    }

    return mach::ok(*query);
});

For a request such as:

GET /search?q=mach

query("q") returns the value of q when it is present.

Query parameters can also be converted directly to a requested type:

const auto page = context.request.query<int>("page");

Because a query parameter may be absent, both forms return std::optional.

You can check for a parameter without retrieving it:

if (context.request.containsQuery("page")) {
    // ...
}

Headers

Use header() to retrieve a request header:

const auto value = context.request.header("X-Example");

if (value) {
    // Use *value
}

Headers may be absent, so header() returns std::optional<std::string_view>.

To test for a header directly:

if (context.request.containsHeader("X-Example")) {
    // ...
}

Cookies

Cookies are accessed in the same way:

const auto session = context.request.cookie("session");

if (session) {
    // Use *session
}

cookie() returns std::optional<std::string_view> because the requested cookie may not be present.

You can check for one without retrieving it:

if (context.request.containsCookie("session")) {
    // ...
}

The Request API

context.request is the main entry point for information about the incoming HTTP request.

It provides access to:

HTTP method and version
request target
raw request body
route parameters
query parameters
headers
cookies

See the Request API reference for the complete interface.

Next, you’ll learn how minimal API handlers read and deserialize request bodies.