Actions

Actions are controller member functions that handle HTTP requests.

A controller can define multiple actions, each mapped to its own HTTP method and route.

Define an Action

An action is an ordinary member function on your controller:

mach::Reply<int> getUser() {
    const int id = request().routeParam<int>("id");
    return ok(id);
}

Because controllers derive from mach::ControllerBase, actions can access the current request and response through request() and response().

They can also use controller response helpers such as ok().

Action Parameters

Controller actions can accept a request body as a parameter:

mach::Reply<User> createUser(CreateUserRequest body) {
    // ...
}

When an action accepts a request body, the body must be the first parameter in the action’s parameter list.

In Mach 1.0, request bodies are the only action parameters supported directly in the function signature. Other request data, such as route parameters, is accessed through request().

For example:

mach::Reply<User> updateUser(UpdateUserRequest body) {
    const int id = request().routeParam<int>("id");
    // ...
}

Request body binding is covered in more detail in the Model Binding guide.

Map an Action

Actions are mapped inside the controller’s configure() function using mach::ControllerBuilder:

static void configure(mach::ControllerBuilder<UsersController>& builder) {
    builder.mapGet("/{id:int}", &UsersController::getUser);
}

The first argument is the route relative to the controller’s base route.

The second argument is a pointer to the controller action that should handle matching requests.

For example:

class UsersController final : public mach::ControllerBase {
public:
    inline static constexpr std::string_view route = "/users";

    mach::Reply<int> getUser() {
        const int id = request().routeParam<int>("id");
        return ok(id);
    }

    static void configure(mach::ControllerBuilder<UsersController>& builder) {
        builder.mapGet("/{id:int}", &UsersController::getUser);
    }
};

This action handles:

GET /users/{id:int}

HTTP Methods

ControllerBuilder provides mapping functions for the HTTP methods supported by Mach:

builder.mapGet("/", &UsersController::getUsers);
builder.mapPost("/", &UsersController::createUser);
builder.mapPut("/{id:int}", &UsersController::replaceUser);
builder.mapPatch("/{id:int}", &UsersController::updateUser);
builder.mapDelete("/{id:int}", &UsersController::deleteUser);
builder.mapHead("/", &UsersController::headUsers);

Each mapping creates a separate endpoint.

The HTTP method is part of the route match, so different actions can use the same route with different methods.

Controller Routes and Action Routes

Action routes are relative to the controller’s base route.

For example:

inline static constexpr std::string_view route = "/users";

combined with:

builder.mapGet("/{id:int}", &UsersController::getUser);

produces:

GET /users/{id:int}

This keeps the shared portion of related routes in one place.

Accessing the Request and Response

Controller actions can access the current request using:

request()

and the current response using:

response()

For example, route parameters can be read directly from the request:

mach::Reply<int> getUser() {
    const int id = request().routeParam<int>("id");
    return ok(id);
}

You will see more ways to read request data in the Model Binding guide.

Multiple Actions

A controller can define as many related actions as it needs:

class UsersController final : public mach::ControllerBase {
public:
    inline static constexpr std::string_view route = "/users";

    mach::Reply<std::string> getUsers() {
        return ok("Users");
    }

    mach::Reply<int> getUser() {
        const int id = request().routeParam<int>("id");
        return ok(id);
    }

    mach::Reply<> deleteUser() {
        const int id = request().routeParam<int>("id");
        return noContent();
    }

    static void configure(mach::ControllerBuilder<UsersController>& builder) {
        builder.mapGet("/", &UsersController::getUsers);
        builder.mapGet("/{id:int}", &UsersController::getUser);
        builder.mapDelete("/{id:int}", &UsersController::deleteUser);
    }
};

Keeping related actions in the same controller makes their routes and request handling easier to discover and maintain.

Tip

Keep configure() focused on route mapping. Put the actual request-handling logic in your controller actions rather than inside the configuration function.

---

Next, you’ll learn how Mach binds request data to controller actions.