Attribute Macro route

#[route]

Define a route for requests to a given path.

The #[route] macro can be used to define routes that match multiple HTTP methods, or non-standard ones (e.g. QUERY). Prefer one of the short-hand attributes if you need to match a standard HTTP method: #[get], #[post], #[put], #[patch], #[delete], #[head], and #[options].

Example: Multiple methods

use pavex::{route, Response};

#[route(method = ["GET", "HEAD"], path = "/users/{id}")]
//      👆 Multiple methods
pub async fn get_or_head_user(/* */) -> Response {
    // [...]
}

Guide

Check out the “Routing” section of Pavex’s guide for a thorough introduction to routing in Pavex applications.

Registration

You can register a route with your application in two ways:

• Use Blueprint::route to register a single route
• Use Blueprint::routes to register multiple routes in bulk

The #[route] macro generates a constant that you can use to refer to the route when invoking Blueprint::route.

Arguments

The sections below provide an exhaustive list of all the arguments supported by the route macro:

Name	Kind	Required
method	Argument	Yes*
path	Argument	Yes
id	Argument	No
allow	Argument	No

* The method argument is required unless allow(any_method) is specified.

method

The method argument specifies the HTTP method(s) that this route will match. You can specify a single method or multiple methods.

method is required unless you specified allow(any_method) to accept any HTTP method.

Example

Single method:

use pavex::{route, Response};

#[route(method = "POST", path = "/users/{id}")]
//       👆 Single method
pub async fn create_user(/* */) -> Response {
    // [...]
}

Multiple methods:

use pavex::{route, Response};

#[route(method = ["GET", "HEAD"], path = "/users/{id}")]
//       👆 Multiple methods
pub async fn get_or_head_user(/* */) -> Response {
    // [...]
}

path

The path argument specifies the URL path pattern that this route will match.

The path can contain parameter placeholders in the format {parameter_name} that will be extracted and passed to your handler function.

Example

use pavex::{route, Response};

#[route(method = "GET", path = "/users/{id}/posts/{post_id}")]
//                            👆 Path with multiple parameters
pub async fn get_user_post(/* */) -> Response {
    // [...]
}

id

By default, Pavex generates a constant named after your function (converted to UPPER_SNAKE_CASE) that you use when registering the route.

The id argument allows you to customize the name of the generated constant.

Example

Using the default generated identifier:

use pavex::{route, Response, Blueprint};

#[route(method = "GET", path = "/users/{id}")]
pub async fn get_user(/* */) -> Response {
    // [...]
}

let mut bp = Blueprint::new();
// The generated constant is named `GET_USER`
bp.route(GET_USER);

Using a custom identifier:

use pavex::{route, Response, Blueprint};

#[route(method = "GET", path = "/users/{id}", id = "USER_ROUTE")]
//                                            👆 Custom identifier
pub async fn get_user(/* */) -> Response {
    // [...]
}

let mut bp = Blueprint::new();
// Use the custom identifier when registering
bp.route(USER_ROUTE);

allow

The allow argument can be used to enable additional behaviors for this route.

Currently, the following values are supported:

• non_standard_methods: Allow non-standard HTTP methods
• any_method: Match any HTTP method. It matches non-standard methods if non_standard_methods is also enabled.

Example: Non-standard method

Allow non-standard methods:

use pavex::{route, Response};

#[route(method = "QUERY", path = "/users", allow(non_standard_methods))]
//                                         👆 Allow non-standard methods
pub async fn query_users() -> Response {
    // [...]
}

Example: Any standard method

Allow any method (no need to specify method):

use pavex::{route, Response};

#[route(path = "/webhook", allow(any_method))]
//                         👆 Allow any HTTP method
pub async fn webhook() -> Response {
    // [...]
}

Example: Arbitrary methods

Allow any method, including non-standard ones:

use pavex::{route, Response};

#[route(path = "/webhook", allow(any_method, non_standard_methods))]
//                         👆 Allow any HTTP method, including non-standard ones
pub async fn webhook() -> Response {
    // [...]
}