How to Make an API Endpoint Accept POST Requests with an Optional JSON body in axum?

What is axum?

axum is a very popular web application framework in the Rust world.

How does axum handle incoming requests?

Like many other web application frameworks, axum routes the incoming requests to handlers.

What is a handler?

In axum, a handler is an async function that accepts zero or more “extractors” as arguments and returns something that can be converted into a response.

What is an extractor?

In axum, an extractor is a type for extracting data from requests, which implements FromRequest or FromRequestParts.

For example, Json is an extractor that consumes the request body and deserializes it as JSON into some target type:

use axum::{
    Json,
    routing::post,
    Router,
};
use serde::Deserialize;

#[derive(Deserialize)]
struct CreateUser {
    email: String,
    password: String,
}

async fn create_user(Json(payload): Json<CreateUser>) {
    // ...
}

let app = Router::new().route("/users", post(create_user));

We can spot a few things in the above example:

1. the async function create_user() is the handler, which is set up to handle POST requests against the /users endpoint
2. the function argument Json(payload) is a Json extractor that consumes the JSON body and deserializes it as JSON into the target type CreateUser

How to make an API endpoint accept POST requests with an optional JSON body?

All extractors defined in axum will reject the request if it doesn’t match. If you wish to make an extractor optional, you can wrap it in Option:

use axum::{
    Json,
    routing::post,
    Router,
};
use serde_json::Value;

async fn create_user(payload: Option<Json<Value>>) {
    if let Some(payload) = payload {
        // We got a valid JSON payload
    } else {
        // Payload wasn't valid JSON
    }
}
let app = Router::new().route("/users", post(create_user));