Struct Path

pub struct Path<T>(pub T);

Extractor that will get captures from the URL and parse them using serde.

Any percent encoded parameters will be automatically decoded. The decoded parameters must be valid UTF-8, otherwise Path will fail and return a 400 Bad Request response.

Option<Path<T>> behavior

You can use Option<Path<T>> as an extractor to allow the same handler to be used in a route with parameters that deserialize to T, and another route with no parameters at all.

Example

These examples assume the serde feature of the uuid crate is enabled.

One Path can extract multiple captures. It is not necessary (and does not work) to give a handler more than one Path argument.

use axum::{
    extract::Path,
    routing::get,
    Router,
};
use uuid::Uuid;

async fn users_teams_show(
    Path((user_id, team_id)): Path<(Uuid, Uuid)>,
) {
    // ...
}

let app = Router::new().route("/users/{user_id}/team/{team_id}", get(users_teams_show));

If the path contains only one parameter, then you can omit the tuple.

use axum::{
    extract::Path,
    routing::get,
    Router,
};
use uuid::Uuid;

async fn user_info(Path(user_id): Path<Uuid>) {
    // ...
}

let app = Router::new().route("/users/{user_id}", get(user_info));

Path segments also can be deserialized into any type that implements serde::Deserialize. This includes tuples and structs:

use axum::{
    extract::Path,
    routing::get,
    Router,
};
use serde::Deserialize;
use uuid::Uuid;

// Path segment labels will be matched with struct field names
#[derive(Deserialize)]
struct Params {
    user_id: Uuid,
    team_id: Uuid,
}

async fn users_teams_show(
    Path(Params { user_id, team_id }): Path<Params>,
) {
    // ...
}

// When using tuples the path segments will be matched by their position in the route
async fn users_teams_create(
    Path((user_id, team_id)): Path<(String, String)>,
) {
    // ...
}

let app = Router::new().route(
    "/users/{user_id}/team/{team_id}",
    get(users_teams_show).post(users_teams_create),
);

If you wish to capture all path parameters you can use HashMap or Vec:

use axum::{
    extract::Path,
    routing::get,
    Router,
};
use std::collections::HashMap;

async fn params_map(
    Path(params): Path<HashMap<String, String>>,
) {
    // ...
}

async fn params_vec(
    Path(params): Path<Vec<(String, String)>>,
) {
    // ...
}

let app = Router::new()
    .route("/users/{user_id}/team/{team_id}", get(params_map).post(params_vec));

Providing detailed rejection output

If the URI cannot be deserialized into the target type the request will be rejected and an error response will be returned. See customize-path-rejection for an example of how to customize that error.

Tuple Fields

0: T

Trait Implementations

impl<T> Debug for Path<T>

where T: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Deref for Path<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &<Path<T> as Deref>::Target

Dereferences the value.

impl<T> DerefMut for Path<T>

fn deref_mut(&mut self) -> &mut <Path<T> as Deref>::Target

Mutably dereferences the value.

impl<T, S> FromRequestParts<S> for Path<T>

where T: DeserializeOwned + Send, S: Send + Sync,

type Rejection = PathRejection

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( parts: &mut Parts, _state: &S, ) -> Result<Path<T>, <Path<T> as FromRequestParts<S>>::Rejection>

Perform the extraction.

impl<T, S> OptionalFromRequestParts<S> for Path<T>

where T: DeserializeOwned + Send + 'static, S: Send + Sync,

type Rejection = PathRejection

If the extractor fails, it will use this “rejection” type.

async fn from_request_parts( parts: &mut Parts, _state: &S, ) -> Result<Option<Path<T>>, <Path<T> as OptionalFromRequestParts<S>>::Rejection>

Perform the extraction.