Defining Endpoints

Minimal API endpoints are mapped directly on the application using methods such as mapGet() and mapPost().

Each mapping associates an HTTP method and route with a handler function.

Map an Endpoint

A minimal endpoint consists of a route and a handler:

app.mapGet("/hello", [] {
    return mach::ok("Hello!");
});

This endpoint handles:

GET /hello

When the route matches, Mach invokes the handler to produce the response.

HTTP Methods

Mach provides mapping functions for the supported HTTP methods:

app.mapGet("/users", [] {
    return mach::ok("GET");
});

app.mapPost("/users", [] {
    return mach::ok("POST");
});

app.mapPut("/users/{id:int}", [] {
    return mach::ok("PUT");
});

app.mapPatch("/users/{id:int}", [] {
    return mach::ok("PATCH");
});

app.mapDelete("/users/{id:int}", [] {
    return mach::noContent();
});

app.mapHead("/users", [] {
    return mach::ok();
});

The available mapping functions are:

HTTP method	Mapping function
`GET`	`mapGet()`
`POST`	`mapPost()`
`PUT`	`mapPut()`
`PATCH`	`mapPatch()`
`DELETE`	`mapDelete()`
`HEAD`	`mapHead()`

Route Patterns

Minimal APIs use the same route patterns and constraints as the rest of Mach.

For example:

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

There is no separate routing syntax for minimal APIs. Static segments, route parameters, constraints, and route precedence all behave the same way.

For a complete explanation of route matching, see the Routing guides.

Handler Functions

Minimal API handlers can either return a mach::Reply<T> or return void.

Returning a Reply

Most handlers return a reply describing the HTTP result:

app.mapGet("/status", [] {
    return mach::ok("Running");
});

Mach uses the returned reply to produce the response.

Returning Void

A handler can instead return void and modify the response directly through mach::Context&:

app.mapGet("/status", [](mach::Context& context) {
    context.response.status(mach::http::StatusCode::Ok);
    context.response.body("Running");
});

Because the handler has no return value, the response is defined through context.response.

The Response Data guide covers direct response manipulation in more detail, while the Results guide covers Reply<T> and Mach’s result helpers.

Handler Parameters

Handlers can be parameterless:

app.mapGet("/status", [] {
    return mach::ok("Running");
});

or receive the current mach::Context& when they need access to request or response data:

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

Handlers can also receive a strongly typed request body. Minimal API handlers support between zero and two parameters: the context, a request body, or both in either order.

Request body parameters are covered in detail in the Request Bodies guide.

Defining Multiple Endpoints

A Mach application can map as many minimal endpoints as needed:

mach::AppBuilder builder;
auto app = builder.build();

app.mapGet("/", [] {
    return mach::ok("Home");
});

app.mapGet("/health", [] {
    return mach::ok("Healthy");
});

app.mapPost("/users", [] {
    return mach::ok("Created user");
});

return app.run();

Each endpoint is registered independently and participates in the same routing system.

Next, you’ll learn how minimal API handlers access request data.