Query Parameters

Volga supports extraction of query parameters into dedicated struct by using Query<T>. Where T should be either deserializable struct or HashMap. If you'd like to use a struct, similarly to NamedPath<T> for route params, make sure that you also have serde installed.

Access Query Parameters

To demonstrate how to access query parameters, consider the following example:

use volga::{App, Query, ok};
use serde::Deserialize;

#[derive(Deserialize)]
struct Params {
    name: String,
}

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let mut app = App::new();

    app.map_get("/hello", |params: Query<Params>| async move {
        ok!("Hello {}!", params.name)
    });

    app.run().await
}

Testing the API with Query Parameters

You can test the API by making requests with query parameters:

> curl "http://localhost:7878/hello?name=John"
Hello John!

> curl "http://localhost:7878/hello?name=Jane"
Hello Jane!

> curl "http://localhost:7878/hello?name=World"
Hello World!

Handling Multiple Query Parameters

For APIs that require multiple query parameters, you can set them up similarly:

use volga::{App, Query, ok};
use serde::Deserialize;

#[derive(Deserialize)]
struct Params {
    name: String,
    age: u32,
    email: String,
}

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let mut app = App::new();

    app.map_get("/hello", |params: Query<Params>| async move {
        // Here you can directly access the params struct fields
        ok!("Hello {} (email: {})! Your age is: {}", params.name, params.email, params.age)
    });

    app.run().await
}

Testing this with multiple query parameters will yield:

> curl "http://localhost:7878/hello?name=John&age=33&email=john@email.com"
Hello John (email: john@email.com)! Your age is: 33

Handle optional params

For the example above if we run the curl command by ignoring some parameter, e.g. email we'll get the 400 BAD REQUEST response:

> curl "http://localhost:7878/hello?name=John&age=33"

< HTTP/1.1 400 BAD REQUEST
Query parsing error: missing field `email`

However, if we want to keep some of the parameters as optional, we can wrap them in Option<T> as follows:

use volga::{App, Query, ok};
use serde::Deserialize;

#[derive(Deserialize)]
struct Params {
    name: String,
    age: u32,
    email: Option<String>, // making email as optional parameter
}

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let mut app = App::new();

    app.map_get("/hello", |params: Query<Params>| async move {
        if let Some(email) = params.email.as_deref() {
            ok!("Hello {} (email: {})! Your age is: {}", params.name, email, params.age)
        } else {
            ok!("Hello {}! Your age is: {}", params.name, params.age)
        }
    });

    app.run().await
}

This guide should provide you with the tools needed to efficiently utilize query parameters in your Volga-based web applications.

You can check out the full example here

Last Updated: