Optional parameter segment in path

[myz-dev]

Hi,

how can I have optional parameters in my query?
My API endpoint always marks the parameters as required. The documentation mentions the nullable property but it also mentions that this is not equal to required :-)

I have found similar questions with a possible solution related to query strings, but at the moment I wonder if I can keep the path syntax I am most familiar with. Related: #622 and #683.

#[utoipa::path(
    get,
    path = "/all_users/{start_id}/{continuation_token}",
    params(
        ("start_id", description = "Optional: Minimum ID of users to look for."),
        ("continuation_token", description = "Optional: Pass when requesting continuation pages."),
    ),
    tag = TAG_USER,
    responses(
        (status = 200, description = "description.", body = [Vec<User>])
    )
)]
pub async fn list_all_users(
    Path((start_id, continuation_token)): Path<(Option<i32>, Option<String>)>,
    DatabaseConnection(mut conn): DatabaseConnection,
) -> Result<Json<Vec<User>>, FetchUserDataError> {
  todo!()
}

[juhaku]

The docs gives some examples of params format https://docs.rs/utoipa/latest/utoipa/attr.path.html#parameter-formats.

You are probably mixing up path params and query params. Path params that are described in the path e.g. /user/{id}/{type} must be present. Path params are always required and cannot be non required. That means that in order to call the path you must give those parameters otherwise the endpoint does not match. You could call the endpoint with /user/null/null which will result in None for both values. But calling it with /user does only give the default behavior of the http framework you are using which is either 404, 415, or 500 most likely.

Query parameters are the ones that are defined after the question mark (?). These parameters be non required. Meaning you can call the endpoint without providing a value for the parameter.

[myz-dev]

Thank you very much for the quick and detailed reply. This has helped me get better understanding of things. I am going to lean more towards using query parameters then :-)

[ReDestroyDeR]

You could still have an endpoint that involves path parameters

For example:

POST /user/write_in_thread
POST /user/write_in_thread/{thread_id}

It's a little bit sad that utoipa does not support such usecase and does not indicate this clearly in the docs. I found only 1 mention of the word required on the path macro page