Routing

Route registration

All the routes exposed by your API must be registered with its Blueprint. In the snippet below you can see the registration of the GET /api/ping route, the one you targeted with your curl request.

app/src/routes/mod.rs

// [...]
use pavex::blueprint::{Blueprint, router::GET};
use pavex::f;

pub fn register(bp: &mut Blueprint) {
    bp.route(GET, "/api/ping", f!(self::ping::get));
}

It specifies:

• The HTTP method (GET)
• The path (/api/ping)
• An unambiguous path to the handler function (self::ping::get), wrapped in the f! macro

Request handlers

The ping function is the handler for the GET /api/ping route:

app/src/routes/ping.rs

use pavex::http::StatusCode;

/// Respond with a `200 OK` status code to indicate that the server is alive
/// and ready to accept new requests.
pub fn get() -> StatusCode {
    StatusCode::OK
}

It's a public function that returns a StatusCode. StatusCode is a valid response type for a Pavex handler since it implements the IntoResponse trait: the framework knows how to convert it into a "full" Response object.

Add a new route

The ping function is fairly boring: it doesn't take any arguments, and it always returns the same response. Let's spice things up with a new route: GET /api/greet/{name}. It takes a dynamic route parameter (name) and we want it to return a success response with Hello, {name} as its body.

Create a new module, greet.rs, in the app/src/routes folder:

app/src/routes/mod.rs

pub mod greet;
pub mod ping;

app/src/routes/greet.rs

use pavex::response::Response;

pub fn get() -> Response {
    todo!()
}

The body of the GET /api/greet/{name} handler is stubbed out with todo!() for now, but we'll fix that soon enough. Let's register the new route with the Blueprint in the meantime:

app/src/routes/mod.rs

// [...]
pub fn register(bp: &mut Blueprint) {
    bp.route(GET, "/api/ping", f!(self::ping::get));
    bp.route(GET, "/api/greet/{name}", f!(self::greet::get)); 
}

Extract path parameters

To access the name route parameter from your new handler you must use the PathParams extractor:

app/src/routes/greet.rs

use pavex::request::path::PathParams;
use pavex::response::Response;

#[PathParams]
pub struct GreetParams {
    pub name: String, 
}

pub fn get(params: PathParams<GreetParams> ) -> Response {
    todo!()
}

You can now return the expected response from the handler:

app/src/routes/greet.rs

use pavex::request::path::PathParams;
use pavex::response::Response;

#[PathParams]
pub struct GreetParams {
    pub name: String,
}

pub fn get(params: PathParams<GreetParams>) -> Response {
    let GreetParams { name } = params.0;
    Response::ok() 
        .set_typed_body(format!("Hello, {name}!")) 
}

Does it work? Only one way to find out! Re-launch the application and issue a new request:

curl http://localhost:8000/api/greet/Ursula

You should see Hello, Ursula! in your terminal if everything went well.