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

[firstdorsal]

I have a similar issue where i got this code:

#[derive(Deserialize, IntoParams)]
pub struct GetFileVersionRequestQueryParams {
    /// download the file/set the content disposition header to attachment
    pub d: Option<bool>,
    /// request setting the caching headers for max-age in seconds
    pub c: Option<u64>,
}

#[utoipa::path(
    get,
    path = "/api/file_versions/content/get/{file_id}/{version}/{app_id}/{app_path}",
    params(
        ("file_id" = Uuid, Path, description = "The ID of the file to retrieve content for"),
        ("version" = Option<u32>, Path, description = "The version of the file to retrieve, if applicable"),
        ("app_id" = Option<Uuid>, Path),
        ("app_path" = Option<String>, Path),
        GetFileVersionRequestQueryParams
    ),
    responses(
        (status = 200, description = "Gets a single files data/content from the server", body = Vec<u8> ),
        (status = 206, description = "Partial content returned due to range request", body = Vec<u8>),
        (status = 404, description = "File not found", body = ApiResponse<EmptyApiResponse>),
        (status = 500, description = "Internal server error retrieving file content", body = ApiResponse<EmptyApiResponse>)
    )
)]
pub async fn get_file_version_content(
    external_user: IntrospectedUser,
    State(ServerState { db, .. }): State<ServerState>,
    Extension(timing): Extension<axum_server_timing::ServerTimingExtension>,
    Path((file_id, version, app_id, app_path)): Path<(
        Uuid,
        Option<u32>,
        Option<Uuid>,
        Option<String>,
    )>,

Now when I request:

/api/file_versions/content/get/01981440-efb7-7cc2-919b-ac50b749f0ef/0/null/null

the response is:

Invalid URL: Cannot parse `app_id` with value `null`: UUID parsing failed: invalid character: expected an optional prefix of `urn:uuid:` followed by [0-9a-fA-F-], found `n` at 1

or if the version is omited:

Invalid URL: Cannot parse value at index 1 with value `null` to a `u32`

[firstdorsal]

When i implement a "fake option" myself this works

/// A "fake" Option type that can be deserialized from a URL path.
/// It treats the literal string "null" as `None` and any other value
/// as `Some(T)`, attempting to parse it using `FromStr`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ToSchema)]
pub enum OptionalPath<T> {
    Some(T),
    None,
}

// Helper visitor for the deserializer
struct FakeOptionVisitor<T> {
    _marker: std::marker::PhantomData<T>,
}

impl<'de, T> Visitor<'de> for FakeOptionVisitor<T>
where
    T: FromStr,
    <T as FromStr>::Err: fmt::Display,
{
    type Value = OptionalPath<T>;

    fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
        formatter
            .write_str("a string literal 'null' or a value that can be parsed into the inner type")
    }

    // This is the core logic. It's called when Serde encounters a string.
    fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
    where
        E: de::Error,
    {
        if value.eq_ignore_ascii_case("null") {
            Ok(OptionalPath::None)
        } else {
            // Attempt to parse the string into the inner type T
            T::from_str(value)
                .map(OptionalPath::Some)
                .map_err(|e| de::Error::custom(format!("failed to parse '{}': {}", value, e)))
        }
    }
}

// The custom Deserialize implementation
impl<'de, T> Deserialize<'de> for OptionalPath<T>
where
    T: FromStr,
    <T as FromStr>::Err: fmt::Display,
{
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        // We tell Serde to expect a string and use our visitor to handle it.
        deserializer.deserialize_str(FakeOptionVisitor {
            _marker: std::marker::PhantomData,
        })
    }
}

// Optional: Implement `Into<Option<T>>` for easy conversion to a standard `Option`.
impl<T> From<OptionalPath<T>> for Option<T> {
    fn from(fake_option: OptionalPath<T>) -> Self {
        match fake_option {
            OptionalPath::Some(value) => Some(value),
            OptionalPath::None => None,
        }
    }
}

#[utoipa::path(
    get,
    path = "/api/file_versions/content/get/{file_id}/{version}/{app_id}/{app_path}",
    params(
        ("file_id" = Uuid, Path, description = "The ID of the file to retrieve content for"),
        ("version" = OptionalPath<u32>, Path, description = "The version of the file to retrieve, if left empty, the latest version will be returned"),
        ("app_id" = OptionalPath<Uuid>, Path, description = "The ID of the application that uploaded the file, if left empty, the app id is the filez server itself"),
        ("app_path" = OptionalPath<String>, Path),
        GetFileVersionRequestQueryParams
    ),
    responses(
        (status = 200, description = "Gets a single files data/content from the server", body = Vec<u8> ),
        (status = 206, description = "Partial content returned due to range request", body = Vec<u8>),
        (status = 404, description = "File not found", body = ApiResponse<EmptyApiResponse>),
        (status = 500, description = "Internal server error retrieving file content", body = ApiResponse<EmptyApiResponse>)
    )
)]
pub async fn get_file_version_content(
    external_user: IntrospectedUser,
    State(ServerState { db, .. }): State<ServerState>,
    Extension(timing): Extension<axum_server_timing::ServerTimingExtension>,
    Path((file_id, version, app_id, app_path)): Path<(
        Uuid,
        OptionalPath<u32>,
        OptionalPath<Uuid>,
        OptionalPath<String>,
    )>,