DEV Community: Syeed Talha

CRUD API in Rust Using Axum, SQLite, and sqlx

Syeed Talha — Sun, 03 May 2026 16:31:23 +0000

In this article, we will build a beginner-friendly CRUD API using Rust, Axum, SQLite, and sqlx.

We will build a simple users API where we can:

Create a user
Get all users
Get one user by ID
Update a user
Delete a user

This article uses a clean project structure instead of putting everything inside main.rs.

What We Are Using

We will use:

axum for building the web API
tokio for async runtime
sqlx for async database queries
sqlite as the database
serde for JSON serialization and deserialization

SQLite is a good database for learning because it does not need a separate database server. It stores data inside a local file.

Project Structure

Create a new Rust project:

cargo new axum_sqlite_crud
cd axum_sqlite_crud

Our final project structure will look like this:

axum_sqlite_crud/
├── Cargo.toml
└── src/
    ├── main.rs
    ├── db.rs
    ├── state.rs
    ├── models.rs
    └── handlers.rs

Here is what each file will do:

main.rs      -> starts the server and connects routes
db.rs        -> database connection and table creation
state.rs     -> shared application state
models.rs    -> request and response structs
handlers.rs  -> CRUD handler functions

Step 1: Add Dependencies

Open Cargo.toml and add:

[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }

sqlx = {
    version = "0.8",
    features = [
        "sqlite",
        "runtime-tokio-rustls"
    ]
}

serde = { version = "1", features = ["derive"] }

Step 2: Create `state.rs`

Create this file:

src/state.rs

Add this code:

use sqlx::SqlitePool;

#[derive(Clone)]
pub struct AppState {
    pub db: SqlitePool,
}

Explanation

AppState is used to share application data across routes.

In our case, we want every handler to access the SQLite database connection pool.

The SqlitePool is a database connection pool. Instead of creating a new database connection for every request, the pool manages and reuses connections.

Step 3: Create `models.rs`

Create this file:

src/models.rs

Add this code:

use serde::{Deserialize, Serialize};
use sqlx::FromRow;

#[derive(Debug, Serialize, FromRow)]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
}

#[derive(Debug, Deserialize)]
pub struct CreateUser {
    pub name: String,
    pub email: String,
}

#[derive(Debug, Deserialize)]
pub struct UpdateUser {
    pub name: String,
    pub email: String,
}

Explanation

We created three structs.

User represents the data we return from the database.

pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
}

CreateUser represents the JSON body when creating a new user.

pub struct CreateUser {
    pub name: String,
    pub email: String,
}

UpdateUser represents the JSON body when updating an existing user.

pub struct UpdateUser {
    pub name: String,
    pub email: String,
}

Why `Serialize`?

Serialize allows Rust structs to be converted into JSON responses.

Why `Deserialize`?

Deserialize allows JSON request bodies to be converted into Rust structs.

Why `FromRow`?

FromRow allows sqlx to convert database rows into our User struct.

Step 4: Create `db.rs`

Create this file:

src/db.rs

Add this code:

use sqlx::sqlite::{SqliteConnectOptions, SqlitePoolOptions};
use sqlx::SqlitePool;
use std::str::FromStr;

pub async fn init_db() -> SqlitePool {
    let options = SqliteConnectOptions::from_str("sqlite:test.db")
        .unwrap()
        .create_if_missing(true);

    SqlitePoolOptions::new()
        .max_connections(5)
        .connect_with(options)
        .await
        .unwrap()
}

pub async fn create_table(pool: &SqlitePool) {
    sqlx::query(
        "CREATE TABLE IF NOT EXISTS users (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            name TEXT NOT NULL,
            email TEXT NOT NULL
        )",
    )
    .execute(pool)
    .await
    .unwrap();
}

Explanation

This file handles database setup.

SqliteConnectOptions::from_str("sqlite:test.db")

This tells SQLite to use a database file named:

test.db

If the file does not exist, this line creates it:

.create_if_missing(true)

Without this, you may get an error like:

unable to open database file

Then we create a connection pool:

SqlitePoolOptions::new()
    .max_connections(5)

This means the pool can manage up to 5 database connections.

Then we create a table:

CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT NOT NULL
)

IF NOT EXISTS is important because the table creation code runs every time the app starts. If the table already exists, SQLite will not create it again.

Step 5: Create `handlers.rs`

Create this file:

src/handlers.rs

Add this code:

use axum::{
    extract::{Path, State},
    http::StatusCode,
    Json,
};

use crate::{
    models::{CreateUser, UpdateUser, User},
    state::AppState,
};

pub async fn create_user(
    State(state): State<AppState>,
    Json(payload): Json<CreateUser>,
) -> (StatusCode, Json<User>) {
    let user = sqlx::query_as::<_, User>(
        "INSERT INTO users (name, email)
         VALUES (?, ?)
         RETURNING id, name, email",
    )
    .bind(payload.name)
    .bind(payload.email)
    .fetch_one(&state.db)
    .await
    .unwrap();

    (StatusCode::CREATED, Json(user))
}

pub async fn get_users(
    State(state): State<AppState>,
) -> Json<Vec<User>> {
    let users = sqlx::query_as::<_, User>(
        "SELECT id, name, email FROM users",
    )
    .fetch_all(&state.db)
    .await
    .unwrap();

    Json(users)
}

pub async fn get_user_by_id(
    Path(id): Path<i64>,
    State(state): State<AppState>,
) -> Result<Json<User>, StatusCode> {
    let user = sqlx::query_as::<_, User>(
        "SELECT id, name, email FROM users WHERE id = ?",
    )
    .bind(id)
    .fetch_optional(&state.db)
    .await
    .unwrap();

    match user {
        Some(user) => Ok(Json(user)),
        None => Err(StatusCode::NOT_FOUND),
    }
}

pub async fn update_user(
    Path(id): Path<i64>,
    State(state): State<AppState>,
    Json(payload): Json<UpdateUser>,
) -> Result<Json<User>, StatusCode> {
    let user = sqlx::query_as::<_, User>(
        "UPDATE users
         SET name = ?, email = ?
         WHERE id = ?
         RETURNING id, name, email",
    )
    .bind(payload.name)
    .bind(payload.email)
    .bind(id)
    .fetch_optional(&state.db)
    .await
    .unwrap();

    match user {
        Some(user) => Ok(Json(user)),
        None => Err(StatusCode::NOT_FOUND),
    }
}

pub async fn delete_user(
    Path(id): Path<i64>,
    State(state): State<AppState>,
) -> StatusCode {
    let result = sqlx::query(
        "DELETE FROM users WHERE id = ?",
    )
    .bind(id)
    .execute(&state.db)
    .await
    .unwrap();

    if result.rows_affected() == 0 {
        StatusCode::NOT_FOUND
    } else {
        StatusCode::NO_CONTENT
    }
}

Understanding the Handlers

Now let’s understand the important parts.

`State(state): State<AppState>`

This gives the handler access to shared application state.

Because our AppState contains the database pool, every handler can use:

state.db

to run database queries.

`Json(payload): Json<CreateUser>`

This extracts JSON from the request body.

For example, if the client sends:

{
  "name": "Talha",
  "email": "talha@example.com"
}

Axum converts it into:

CreateUser {
    name: "Talha".to_string(),
    email: "talha@example.com".to_string(),
}

`Path(id): Path<i64>`

This extracts the ID from the URL.

For example:

GET /users/1

Axum takes 1 from the URL and gives it to the handler as:

id = 1

In Axum 0.8, path parameters use curly braces in routes:

"/users/{id}"

not:

"/users/:id"

`.bind()`

This is very important.

Instead of writing SQL like this:

format!("SELECT * FROM users WHERE id = {}", id)

we write:

sqlx::query("SELECT * FROM users WHERE id = ?")
    .bind(id)

This is safer because it helps prevent SQL injection.

`fetch_one`

This is used when we expect one row.

Example:

.fetch_one(&state.db)

We use it after inserting a user because we return the newly created user.

`fetch_all`

This is used when we expect many rows.

Example:

.fetch_all(&state.db)

We use it when getting all users.

`fetch_optional`

This is used when the data may or may not exist.

Example:

.fetch_optional(&state.db)

If the user exists, it returns:

Some(user)

If the user does not exist, it returns:

None

That is why we can return 404 NOT FOUND.

Step 6: Create `main.rs`

Now open:

src/main.rs

Replace everything with:

mod db;
mod handlers;
mod models;
mod state;

use axum::{
    routing::{get, post},
    Router,
};

use db::{create_table, init_db};
use handlers::{
    create_user,
    delete_user,
    get_user_by_id,
    get_users,
    update_user,
};
use state::AppState;

#[tokio::main]
async fn main() {
    let pool = init_db().await;

    create_table(&pool).await;

    let state = AppState { db: pool };

    let app = Router::new()
        .route("/users", post(create_user).get(get_users))
        .route(
            "/users/{id}",
            get(get_user_by_id)
                .put(update_user)
                .delete(delete_user),
        )
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    println!("Server running on http://localhost:3000");

    axum::serve(listener, app).await.unwrap();
}

Understanding `main.rs`

These lines import our other files:

mod db;
mod handlers;
mod models;
mod state;

This means Rust can use code from:

db.rs
handlers.rs
models.rs
state.rs

Then we initialize the database:

let pool = init_db().await;

Then we create the table:

create_table(&pool).await;

Then we create shared state:

let state = AppState { db: pool };

Then we define routes:

.route("/users", post(create_user).get(get_users))

This means:

POST /users -> create user
GET  /users -> get all users

Then:

.route(
    "/users/{id}",
    get(get_user_by_id)
        .put(update_user)
        .delete(delete_user),
)

This means:

GET    /users/{id} -> get one user
PUT    /users/{id} -> update one user
DELETE /users/{id} -> delete one user

Finally, we attach the shared state:

.with_state(state)

Now all handlers can access the database pool.

Step 7: Run the Server

Run:

cargo run

You should see:

Server running on http://localhost:3000

Also, after running the app, you should see a new file in your project:

test.db

That is your SQLite database file.

Step 8: Test the API

You can test using Postman, Thunder Client, or curl.

Create User

Request:

POST http://localhost:3000/users

Body:

{
  "name": "Talha",
  "email": "talha@example.com"
}

curl:

curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Talha","email":"talha@example.com"}'

On Windows CMD, use:

curl -X POST http://localhost:3000/users ^
  -H "Content-Type: application/json" ^
  -d "{\"name\":\"Talha\",\"email\":\"talha@example.com\"}"

Expected response:

{
  "id": 1,
  "name": "Talha",
  "email": "talha@example.com"
}

Get All Users

Request:

GET http://localhost:3000/users

curl:

curl http://localhost:3000/users

Expected response:

[
  {
    "id": 1,
    "name": "Talha",
    "email": "talha@example.com"
  }
]

Get One User

Request:

GET http://localhost:3000/users/1

curl:

curl http://localhost:3000/users/1

Expected response:

{
  "id": 1,
  "name": "Talha",
  "email": "talha@example.com"
}

If the user does not exist, the API returns:

404 NOT FOUND

Update User

Request:

PUT http://localhost:3000/users/1

Body:

{
  "name": "Updated Talha",
  "email": "updated@example.com"
}

curl:

curl -X PUT http://localhost:3000/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Talha","email":"updated@example.com"}'

Windows CMD:

curl -X PUT http://localhost:3000/users/1 ^
  -H "Content-Type: application/json" ^
  -d "{\"name\":\"Updated Talha\",\"email\":\"updated@example.com\"}"

Expected response:

{
  "id": 1,
  "name": "Updated Talha",
  "email": "updated@example.com"
}

Delete User

Request:

DELETE http://localhost:3000/users/1

curl:

curl -X DELETE http://localhost:3000/users/1

If deleted successfully, the API returns:

204 NO CONTENT

If the user does not exist, the API returns:

404 NOT FOUND

Why We Did Not Put Everything in `main.rs`

For very small examples, putting all code in main.rs is okay.

But as your project grows, main.rs becomes hard to read.

This structure is better:

main.rs      -> application startup
db.rs        -> database setup
state.rs     -> shared state
models.rs    -> data types
handlers.rs  -> request handlers

This makes the project easier to understand, maintain, and extend.

Current Limitations

This project is beginner-friendly, but it is not fully production-ready yet.

For production, we should improve:

Error handling instead of using .unwrap()
Database migrations instead of creating tables in code
Validation for user input
Separate service/repository layers for larger apps
Environment variables for database URL

But this version is a strong starting point.

Final Thoughts

In this article, we built a CRUD API using Axum, SQLite, and sqlx.

We learned:

How to connect Axum with SQLite
How to use a database connection pool
How to share database access using state
How to create clean file structure
How to write Create, Read, Update, and Delete handlers
How to test the API using curl or Postman

SQLite is a great choice when you are learning database integration because it is simple, local, and does not require a separate database server.

Once you understand this, switching to PostgreSQL later will be much easier because sqlx supports both SQLite and PostgreSQL.

Sharing Data in Axum State, Arc, Mutex & RwLock

Syeed Talha — Sun, 03 May 2026 11:04:05 +0000

If you're building web APIs in Rust with Axum, you'll quickly hit a very relatable question:

"How do I share a database connection, a config value, or an in-memory cache across my route handlers?"

The answer involves four tools working together: State<T>, Arc<T>, Mutex<T>, and RwLock<T>. Each one does a specific job. By the end of this article, you'll understand what each one is for, when to use which, and how to combine them confidently in Axum 0.8.

Let's go step by step. 🦀

The Problem: Handlers Don't Share Memory by Default

In Axum, each request is handled by an async function. These handlers are independent — they don't automatically have access to shared resources like:

A database connection pool
An API key loaded from environment variables
An in-memory counter or key-value store

You need a way to inject shared data into your handlers safely — especially when multiple requests run concurrently on different threads.

Tool #1 — `Arc<T>`: Shared Ownership Across Threads

Arc stands for Atomically Reference Counted. It lives in Rust's standard library (std::sync::Arc).

Rust's ownership system normally allows only one owner per value. But in a web server, multiple request handlers run at the same time and all need to read the same data. Arc<T> solves this by letting you have multiple owners of the same data. Internally it keeps a count of how many owners exist, and when the last one is dropped, the data is cleaned up.

use std::sync::Arc;

let config = Arc::new(AppConfig {
    db_url: "postgres://localhost/mydb".to_string(),
});

// Both config and config_clone point to the same allocation — no data is copied
let config_clone = Arc::clone(&config);

💡 Arc::clone() is cheap — it just increments the reference count. The actual data is never duplicated.

When is plain Arc<T> enough?
When your data is read-only — like app configuration or feature flags loaded at startup. No mutations means no synchronization needed beyond Arc.

Tool #2 — `State<T>`: Axum's Dependency Injection

State<T> is Axum's built-in extractor for shared application state. An extractor is just something you put in a handler's function signature, and Axum automatically provides it.

use axum::extract::State;

async fn hello_handler(State(config): State<Arc<AppConfig>>) -> String {
    format!("Connected to: {}", config.db_url)
}

You attach your state to the router using .with_state(), and from then on any handler can request it via State<T>:

let app = Router::new()
    .route("/hello", get(hello_handler))
    .with_state(Arc::new(config)); // 👈 attach once, available everywhere

⚠️ Order matters! State must come before body extractors like Json in your handler's parameter list.

Tool #3 — `Mutex<T>`: Exclusive Access for Writes

What if you need to mutate your shared data? Reading and writing at the same time from multiple threads is a data race — and Rust won't let you do it without synchronization.

Mutex<T> (Mutual Exclusion) is the classic solution. It acts as a lock — only one thread can hold it at a time:

use std::sync::{Arc, Mutex};

let counter = Arc::new(Mutex::new(0u64));

// To read or write, you lock() first
let mut val = counter.lock().unwrap();
*val += 1;
// lock is automatically released when `val` is dropped

In an Axum handler:

async fn increment(State(state): State<Arc<AppState>>) -> String {
    let mut count = state.counter.lock().unwrap();
    *count += 1;
    format!("Count is now: {}", *count)
}

The key rule with std::sync::Mutex:

❌ Never hold a std::sync::Mutex lock across an .await point!

// BAD — other tasks can't proceed while this one awaits
let data = state.items.lock().unwrap();
some_async_function().await; // 🔴 still holding the lock!

If you genuinely need to hold a lock across an .await, use tokio::sync::Mutex instead (more on this below).

Tool #4 — `RwLock<T>`: Many Readers, One Writer

Mutex<T> is simple but strict — even reading blocks all other threads. For workloads that are read-heavy, this is wasteful.

Enter RwLock<T> (Read-Write Lock). It has two modes:

Read lock (.read()) — Many threads can hold this simultaneously
Write lock (.write()) — Only one thread can hold this, and it blocks all readers

use std::sync::{Arc, RwLock};

let store = Arc::new(RwLock::new(vec!["hello".to_string()]));

// Multiple readers at the same time — fine!
let data = store.read().unwrap();
println!("{:?}", *data);

// One writer at a time — blocks until all readers are done
let mut data = store.write().unwrap();
data.push("world".to_string());

In an Axum handler:

async fn get_items(State(state): State<Arc<AppState>>) -> String {
    let items = state.store.read().unwrap(); // 🔒 shared read lock
    items.join(", ")
}

async fn add_item(State(state): State<Arc<AppState>>) -> String {
    let mut items = state.store.write().unwrap(); // 🔒 exclusive write lock
    items.push("new item".to_string());
    format!("Total: {}", items.len())
}

💡 Use RwLock when your data is read far more often than it's written. A good rule of thumb: if 80%+ of accesses are reads, RwLock wins.

`std::sync` vs `tokio::sync` — Which Should You Use?

This trips up a lot of beginners. Here's the quick answer:

	`std::sync::Mutex` / `RwLock`	`tokio::sync::Mutex` / `RwLock`
Holding across `.await`	❌ Will panic / cause `!Send` errors	✅ Safe
Performance	✅ Faster (OS-level)	Slightly more overhead
When to use	Lock is held briefly, no `.await` inside	You must hold the lock across async calls

The practical advice: Start with std::sync::Mutex. Only reach for tokio::sync::Mutex if you need to hold the lock while awaiting something.

// std::sync version — fine as long as you drop the lock before .await
{
    let mut data = state.cache.lock().unwrap();
    data.insert("key", "value"); // quick operation
} // lock dropped here ✅
some_async_call().await;

// tokio::sync version — needed if you must hold the lock across await
use tokio::sync::Mutex;
let mut data = state.cache.lock().await; // async lock acquisition
do_something_async().await; // safe to hold the lock here

Choosing the Right Tool

Here's a simple decision tree:

Is your data read-only after startup?
  └── YES → Arc<T>  (no lock needed)
  └── NO (you need to mutate it)
        ├── Reads and writes happen equally?
        │     └── Arc<Mutex<T>>
        └── Reads are much more frequent than writes?
              └── Arc<RwLock<T>>

Do you need to hold the lock across .await points?
  └── YES → tokio::sync::Mutex / tokio::sync::RwLock
  └── NO  → std::sync::Mutex / std::sync::RwLock (preferred)

A Complete Working Example

Let's build a small in-memory key-value store that demonstrates all four tools together.

`Cargo.toml`

[dependencies]
axum = "0.8.9"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"

`main.rs`

use axum::{
    extract::{Path, State},
    routing::{get, post},
    Json, Router,
};
use std::{
    collections::HashMap,
    sync::{Arc, RwLock},
};

// Our shared application state
struct AppState {
    // RwLock because reads (GET) will far outnumber writes (POST)
    store: RwLock<HashMap<String, String>>,
}

#[tokio::main]
async fn main() {
    let shared_state = Arc::new(AppState {
        store: RwLock::new(HashMap::new()),
    });

    let app = Router::new()
        .route("/store/{key}", get(get_value))
        .route("/store", post(set_value))
        .with_state(shared_state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    println!("🚀 Listening on http://localhost:3000");
    axum::serve(listener, app).await.unwrap();
}

// GET /store/:key — many of these can run concurrently
async fn get_value(
    Path(key): Path<String>,
    State(state): State<Arc<AppState>>,
) -> String {
    let store = state.store.read().unwrap(); // shared read lock
    match store.get(&key) {
        Some(val) => val.clone(),
        None => format!("Key '{}' not found", key),
    }
} // read lock released here

// POST /store — exclusive write, blocks readers only for an instant
async fn set_value(
    State(state): State<Arc<AppState>>,
    Json(payload): Json<HashMap<String, String>>,
) -> String {
    let mut store = state.store.write().unwrap(); // exclusive write lock
    let count = payload.len();
    for (k, v) in payload {
        store.insert(k, v);
    }
    format!("Inserted {} key(s). Total keys: {}", count, store.len())
} // write lock released here

Try it out:

# Set some values
curl -X POST http://localhost:3000/store \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "lang": "Rust"}'

# Read them back (concurrent reads are safe!)
curl http://localhost:3000/store/name
curl http://localhost:3000/store/lang

Common Gotchas

❌ Forgetting `.with_state()`

If you use State<T> in a handler but forget to call .with_state() on the router, Axum will panic at startup with a clear error message. Always pair them.

❌ Using `Rc<T>` instead of `Arc<T>`

Rc<T> is single-threaded reference counting. Axum requires Send + Sync because handlers run across threads. Use Arc<T> always.

❌ Holding `std::sync::Mutex` across `.await`

// ❌ This will either panic or cause a compile error
let lock = state.data.lock().unwrap();
some_async_fn().await; // still holding the lock!

Drop the lock before any .await, or switch to tokio::sync::Mutex.

❌ `RwLock` write starvation

If write requests pile up, RwLock can starve. For high-contention scenarios, a Mutex may actually perform better in practice. Profile before optimizing.

Quick Reference Cheatsheet

// Read-only state (config, flags)
Arc<AppConfig>

// Mutable state, equal reads/writes
Arc<Mutex<T>>

// Mutable state, mostly reads
Arc<RwLock<T>>

// Mutable state, must hold lock across .await
Arc<tokio::sync::Mutex<T>>
Arc<tokio::sync::RwLock<T>>

// In your handler signature:
async fn my_handler(State(state): State<Arc<AppState>>) { ... }

// Attach to router:
Router::new()
    .route("/path", get(my_handler))
    .with_state(Arc::new(app_state))

Summary

Here's the full picture:

Arc<T> — enables multiple handlers to own the same data without copying it, safely across threads.
State<T> — Axum's extractor that delivers shared state to your handlers automatically.
Mutex<T> — ensures only one handler modifies mutable data at a time (exclusive lock).
RwLock<T> — allows many concurrent readers or one exclusive writer, great for read-heavy data.

Together they form the idiomatic Rust pattern for safe, performant shared state in concurrent web applications. Once you internalize this, you'll reach for it naturally in every Axum project.

Happy coding!

Got questions or spotted something? Drop a comment below — I'd love to hear from you!

Error Handling in Axum

Syeed Talha — Sat, 02 May 2026 17:06:54 +0000

Axum is a web framework for Rust built on top of Tokio and Hyper. One of its
standout features is a simple and predictable error handling model — once
you understand the pattern, writing safe, expressive web servers becomes
surprisingly natural.

This guide walks you from the very basics to real-world patterns you'll use in
production.

The Core Idea: Errors Must Become Responses

In Axum, every error must eventually become an HTTP response. There is no
unhandled-exception mechanism. If something goes wrong, you decide what the
client sees — a 404, a 500, a JSON error body, or anything else.

The key trait is IntoResponse. Anything that implements it can be returned
from a handler, including error types.

1. The Simplest Error: Return a `StatusCode`

The easiest way to signal an error is to return a StatusCode directly.

use axum::{
    extract::Path,
    http::StatusCode,
    routing::get,
    Router,
};

async fn get_user(Path(id): Path<u32>) -> Result<String, StatusCode> {
    if id == 0 {
        return Err(StatusCode::NOT_FOUND);
    }
    Ok(format!("User #{}", id))
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/users/{id}", get(get_user)); // ✅ use {id}
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Here the handler returns Result<String, StatusCode>. When Ok, Axum sends
the string as a 200 OK. When Err, it sends the status code you chose. Clean
and simple!

2. Returning Richer Errors with Tuples

A bare StatusCode doesn't tell the client why something went wrong. You can
pair a status code with a message using a tuple.

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

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

async fn create_user(
    Json(payload): Json<CreateUser>,
) -> Result<String, (StatusCode, String)> {
    if payload.username.is_empty() {
        return Err((
            StatusCode::BAD_REQUEST,
            "Username cannot be empty".to_string(),
        ));
    }

    Ok(format!("Created user: {}", payload.username))
}

The tuple (StatusCode, String) is automatically turned into a response with
the given status and a text body. Axum knows how to convert it thanks to the
IntoResponse trait.

3. Building a Custom Error Type (The Right Way)

For real applications, you want a single error enum that covers all the things
that can go wrong. Then you implement IntoResponse for it so Axum can turn
your errors into HTTP responses automatically.

use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
    routing::get,
    Router,
};

// Your application's error type
enum AppError {
    NotFound(String),
    Unauthorized,
    InternalError(String),
}

// Teach Axum how to turn your error into a response
impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, message) = match self {
            AppError::NotFound(msg) => (StatusCode::NOT_FOUND, msg),
            AppError::Unauthorized => (
                StatusCode::UNAUTHORIZED,
                "You are not authorized".to_string(),
            ),
            AppError::InternalError(msg) => (StatusCode::INTERNAL_SERVER_ERROR, msg),
        };

        (status, message).into_response()
    }
}

// Now use it in your handlers
async fn get_document(Path(id): Path<u32>) -> Result<String, AppError> {
    if id == 99 {
        return Err(AppError::Unauthorized);
    }
    if id > 100 {
        return Err(AppError::NotFound(format!("Document {} not found", id)));
    }
    Ok(format!("Document #{}", id))
}

This is the pattern you'll use most often. One error type, one place to define
what each error looks like to clients.

4. Returning JSON Errors

APIs usually return JSON error bodies instead of plain text. Here's how to
return structured JSON from your error type.

use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
    Json,
};
use serde::Serialize;

#[derive(Serialize)]
struct ErrorBody {
    error: String,
    code: u16,
}

enum ApiError {
    NotFound(String),
    BadRequest(String),
    Internal,
}

impl IntoResponse for ApiError {
    fn into_response(self) -> Response {
        let (status, message) = match self {
            ApiError::NotFound(msg) => (StatusCode::NOT_FOUND, msg),
            ApiError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg),
            ApiError::Internal => (
                StatusCode::INTERNAL_SERVER_ERROR,
                "Something went wrong".to_string(),
            ),
        };

        let body = Json(ErrorBody {
            error: message,
            code: status.as_u16(),
        });

        (status, body).into_response()
    }
}

Now your clients get responses like:

{
  "error": "Document 999 not found",
  "code": 404
}

5. Converting `?` Errors with `From`

In real code, you'll use ? to propagate errors from libraries like database
drivers or HTTP clients. You can implement From<SomeError> for AppError to
make this seamless.

use std::num::ParseIntError;

enum AppError {
    BadRequest(String),
    Internal(String),
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        // ... (same as above)
    }
}

// Convert ParseIntError into AppError automatically
impl From<ParseIntError> for AppError {
    fn from(err: ParseIntError) -> Self {
        AppError::BadRequest(format!("Invalid number: {}", err))
    }
}

async fn parse_id(Path(raw): Path<String>) -> Result<String, AppError> {
    // The `?` operator automatically calls From<ParseIntError> here
    let id: u32 = raw.parse()?;
    Ok(format!("Parsed id: {}", id))
}

The ? after raw.parse() will, on failure, call your From impl and return
an Err(AppError::BadRequest(...)) — no manual conversion needed.

6. Using `anyhow` for Quick Prototyping

The anyhow crate is popular for applications where you don't need fine-grained
error types yet. You can bridge it into Axum with a small wrapper.

use anyhow::Context;
use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
};

// A wrapper so we can impl IntoResponse for anyhow::Error
struct AnyhowError(anyhow::Error);

impl IntoResponse for AnyhowError {
    fn into_response(self) -> Response {
        (
            StatusCode::INTERNAL_SERVER_ERROR,
            format!("Internal error: {}", self.0),
        )
            .into_response()
    }
}

// Allow using `?` on anyhow::Result in handlers
impl<E: Into<anyhow::Error>> From<E> for AnyhowError {
    fn from(err: E) -> Self {
        AnyhowError(err.into())
    }
}

async fn risky_handler() -> Result<String, AnyhowError> {
    let data = std::fs::read_to_string("config.txt")
        .context("Failed to read config file")?;
    Ok(data)
}

7. Handler-Level Error Handling with `HandleError`

Sometimes you use a Tower Service or middleware that returns errors Axum
doesn't know how to handle. The HandleError layer lets you convert those.

use axum::{
    error_handling::HandleError,
    http::StatusCode,
    routing::get,
    Router,
};
use std::convert::Infallible;

async fn might_fail() -> Result<String, String> {
    Err("Something broke".to_string())
}

// Wrap the service to handle its errors
let service = tower::service_fn(|_req| async {
    Ok::<_, Infallible>("ok")
});

let handled = HandleError::new(service, |err: String| async move {
    (StatusCode::INTERNAL_SERVER_ERROR, err)
});

This is more advanced and mainly relevant when integrating third-party Tower
services.

Quick Reference

Pattern	Best For
`Result<T, StatusCode>`	Simple, code-only errors
`Result<T, (StatusCode, String)>`	Errors with a message
Custom `enum` + `impl IntoResponse`	Production apps with typed errors
`impl IntoResponse` returning `Json`	APIs that return JSON error bodies
`impl From<LibError> for AppError`	Using `?` with library errors
`anyhow` wrapper	Quick prototypes or scripts

Summary

Axum's error handling boils down to one rule: your errors must implement
IntoResponse. Once they do, you can use Result<T, YourError> in any
handler and Axum handles the rest.

The recommended path for most apps:

Define an enum AppError with variants for each failure mode.
Implement IntoResponse for it (returning JSON is usually best).
Implement From<LibError> for AppError for each third-party error type you use with ?.
Return Result<impl IntoResponse, AppError> from your handlers.

That's it. No magic, no hidden panics — just clean, explicit error paths.

Build In-Memory CRUD API in Axum (Rust)

Syeed Talha — Sat, 02 May 2026 14:01:38 +0000

If you're learning Rust and want to build APIs, Axum is one of the best frameworks to start with.

In this tutorial, we'll build a simple CRUD API (Create, Read, Update, Delete) using:

✅ Axum
✅ In-memory storage (no database)
✅ Beginner-friendly concepts

What We Will Build

A simple User API with these endpoints:

Method	Route	Description
POST	`/users`	Create a user
GET	`/users`	Get all users
GET	`/user/:id`	Get a single user
PUT	`/user/:id`	Update a user
DELETE	`/user/:id`	Delete a user

Step 1: Setup Dependencies

Add this to your Cargo.toml:

[dependencies]
axum = "0.7"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"

Step 2: Define Our Data

#[derive(Debug, Serialize, Deserialize, Clone)]
struct User {
    id: u32,
    name: String,
    email: String,
}

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

User → the stored data structure
CreateUser → the incoming request body

Step 3: App State (In-Memory Database)

type AppState = Arc<Mutex<Vec<User>>>;

We use:

Vec<User> → to store users
Mutex → for safe concurrent access
Arc → to share state across threads

Step 4: Create User (POST)

async fn create_user(
    State(state): State<AppState>,
    Json(body): Json<CreateUser>,
) -> (StatusCode, Json<User>) {
    let mut users = state.lock().unwrap();
    let new_id = users.last().map_or(1, |u| u.id + 1);
    let new_user = User {
        id: new_id,
        name: body.name,
        email: body.email,
    };
    users.push(new_user.clone());
    (StatusCode::CREATED, Json(new_user))
}

Step 5: Get All Users (GET)

async fn user_list(State(state): State<AppState>) -> Json<Vec<User>> {
    let users = state.lock().unwrap();
    Json(users.clone())
}

Step 6: Get Single User

async fn get_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> Result<Json<User>, StatusCode> {
    let users = state.lock().unwrap();

    if let Some(user) = users.iter().find(|u| u.id == id) {
        Ok(Json(user.clone()))
    } else {
        Err(StatusCode::NOT_FOUND)
    }
}

Step 7: Update User

async fn update_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
    Json(body): Json<CreateUser>,
) -> Result<Json<User>, StatusCode> {
    let mut users = state.lock().unwrap();

    if let Some(user) = users.iter_mut().find(|u| u.id == id) {
        user.name = body.name;
        user.email = body.email;
        Ok(Json(user.clone()))
    } else {
        Err(StatusCode::NOT_FOUND)
    }
}

Step 8: Delete User

async fn delete_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> StatusCode {
    let mut users = state.lock().unwrap();

    if let Some(pos) = users.iter().position(|u| u.id == id) {
        users.remove(pos);
        StatusCode::NO_CONTENT
    } else {
        StatusCode::NOT_FOUND
    }
}

Step 9: Setup Router & Main

#[tokio::main]
async fn main() {
    let state: AppState = Arc::new(Mutex::new(vec![]));

    let app = Router::new()
        .route("/users", get(user_list).post(create_user))
        .route(
            "/user/:id",
            get(get_user)
                .put(update_user)
                .delete(delete_user),
        )
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    println!("Server running on http://localhost:3000");
    axum::serve(listener, app).await.unwrap();
}

Full Code (Mutex Version)

use axum::{
    extract::{State, Path},
    http::StatusCode,
    routing::{get, post, put, delete},
    Json,
    Router,
};

use serde::{Deserialize, Serialize};
use std::sync::{Arc, Mutex};

#[derive(Debug, Serialize, Deserialize, Clone)]
struct User {
    id: u32,
    name: String,
    email: String,
}

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

type AppState = Arc<Mutex<Vec<User>>>;

async fn create_user(
    State(state): State<AppState>,
    Json(body): Json<CreateUser>,
) -> (StatusCode, Json<User>) {
    let mut users = state.lock().unwrap();
    let new_user = User {
        id: users.len() as u32 + 1,
        name: body.name,
        email: body.email,
    };
    users.push(new_user.clone());
    (StatusCode::CREATED, Json(new_user))
}

async fn user_list(State(state): State<AppState>) -> Json<Vec<User>> {
    let users = state.lock().unwrap();
    Json(users.clone())
}

async fn get_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> Result<Json<User>, StatusCode> {
    let users = state.lock().unwrap();
    if let Some(user) = users.iter().find(|u| u.id == id) {
        Ok(Json(user.clone()))
    } else {
        Err(StatusCode::NOT_FOUND)
    }
}

async fn update_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
    Json(body): Json<CreateUser>,
) -> Result<Json<User>, StatusCode> {
    let mut users = state.lock().unwrap();
    if let Some(user) = users.iter_mut().find(|u| u.id == id) {
        user.name = body.name;
        user.email = body.email;
        Ok(Json(user.clone()))
    } else {
        Err(StatusCode::NOT_FOUND)
    }
}

async fn delete_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> StatusCode {
    let mut users = state.lock().unwrap();
    if let Some(pos) = users.iter().position(|u| u.id == id) {
        users.remove(pos);
        StatusCode::NO_CONTENT
    } else {
        StatusCode::NOT_FOUND
    }
}

#[tokio::main]
async fn main() {
    let state: AppState = Arc::new(Mutex::new(vec![]));

    let app = Router::new()
        .route("/users", post(create_user))
        .route("/users", get(user_list))
        .route("/user/:id", put(update_user))
        .route("/user/:id", delete(delete_user))
        .route("/user/:id", get(get_user))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    println!("Server running on http://localhost:3000");
    axum::serve(listener, app).await.unwrap();
}

Bonus: Async RwLock Version

For better read performance (multiple concurrent reads), use tokio::sync::RwLock instead of Mutex:

use axum::{
    extract::State,
    http::StatusCode,
    routing::{get, post, put, delete},
    extract::{Path, Json},
    Router,
};
use serde::{Deserialize, Serialize};
use std::sync::Arc;
use tokio::sync::RwLock;

#[derive(Debug, Clone, Serialize, Deserialize)]
struct User {
    id: u32,
    name: String,
    email: String,
}

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

type AppState = Arc<RwLock<Vec<User>>>;

async fn create_user(
    State(state): State<AppState>,
    Json(body): Json<CreateUser>,
) -> (StatusCode, Json<User>) {
    let mut users = state.write().await;
    let new_id = users.last().map_or(1, |u| u.id + 1);
    let new_user = User {
        id: new_id,
        name: body.name,
        email: body.email,
    };
    users.push(new_user.clone());
    (StatusCode::CREATED, Json(new_user))
}

async fn user_list(State(state): State<AppState>) -> Json<Vec<User>> {
    let users = state.read().await;
    Json(users.clone())
}

async fn get_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> Result<Json<User>, StatusCode> {
    let users = state.read().await;
    if let Some(user) = users.iter().find(|u| u.id == id) {
        Ok(Json(user.clone()))
    } else {
        Err(StatusCode::NOT_FOUND)
    }
}

async fn delete_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> StatusCode {
    let mut users = state.write().await;
    if let Some(pos) = users.iter().position(|u| u.id == id) {
        users.remove(pos);
        StatusCode::NO_CONTENT
    } else {
        StatusCode::NOT_FOUND
    }
}

async fn update_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
    Json(body): Json<User>,
) -> Result<Json<User>, StatusCode> {
    let mut users = state.write().await;
    if let Some(user) = users.iter_mut().find(|u| u.id == id) {
        user.name = body.name;
        user.email = body.email;
        Ok(Json(user.clone()))
    } else {
        Err(StatusCode::NOT_FOUND)
    }
}

#[tokio::main]
async fn main() {
    let state: AppState = Arc::new(RwLock::new(vec![]));

    let app = Router::new()
        .route("/users", get(user_list))
        .route("/users", post(create_user))
        .route("/user/{id}", get(get_user))
        .route("/user/{id}", delete(delete_user))
        .route("/user/{id}", put(update_user))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    println!("Server running on http://localhost:3000");
    axum::serve(listener, app).await.unwrap();
}

Mutex vs RwLock: Use Mutex for simplicity. Use RwLock when you have many reads and few writes — it allows multiple readers simultaneously.

How to Test

Use Postman or curl to test your endpoints.

Create a user:

POST /users
Content-Type: application/json

{
  "name": "John",
  "email": "john@example.com"
}

Get all users:

GET /users

Get a single user:

GET /user/1

Update a user:

PUT /user/1
Content-Type: application/json

{
  "name": "John Updated",
  "email": "john_updated@example.com"
}

Delete a user:

DELETE /user/1

Key Concepts You Learned

Axum routing — how to define and chain HTTP routes
State management — sharing data across handlers with Arc<Mutex<T>>
JSON handling — extracting request bodies and returning JSON responses
Path parameters — reading dynamic values from the URL
CRUD operations — implementing all four basic data operations

What's Next?

Now that you have the basics down, you can level up by:

Replacing in-memory storage with PostgreSQL (using sqlx)
Adding input validation (using validator)
Adding authentication (JWT tokens)
Switching to tokio::sync::RwLock for better concurrency

Happy coding!

Understanding the match Keyword in Rust with Examples

Syeed Talha — Thu, 30 Apr 2026 02:39:24 +0000

If you've ever written a long if/else chain and thought "there must be a cleaner way" — match is Rust's answer. It lets you check a value against a list of patterns and run different code for each one.

By the end of this post, you'll understand exactly how match works, why Rust forces you to use it a certain way, and how it handles real-world things like errors.

What is `match`?

match compares a value against a list of patterns. The first matching pattern wins, and the code next to it runs.

Here's the simplest example — matching a number:

let number = 2;

match number {
    1 => println!("One"),
    2 => println!("Two"),
    3 => println!("Three"),
    _ => println!("Something else"),
}
// Output: Two

Each pattern => code pair is called an arm. Rust checks arms from top to bottom and stops at the first match.

The anatomy of a match expression

match  <value>  {
    pattern1 => code to run,
    pattern2 => code to run,
    _        => code to run,  // catch-all
}

match — the keyword
<value> — the thing you're checking
each pattern => code — one arm
_ — the catch-all (like default in other languages)

The catch-all pattern: `_`

Rust requires you to cover every possible value. If you only match 1, 2, and 3 — what happens when the number is 99? You must either list every possibility or use _ as a catch-all.

⚠️ Compile error without it! If you forget the catch-all and don't cover every possible value, Rust will refuse to compile your code. This is a feature — it prevents bugs.

let day = 5;

let name = match day {
    1 => "Monday",
    2 => "Tuesday",
    3 => "Wednesday",
    4 => "Thursday",
    5 => "Friday",
    6 => "Saturday",
    7 => "Sunday",
    _ => "Invalid day",  // covers anything outside 1–7
};

println!("Day {} is {}", day, name);
// Output: Day 5 is Friday

Notice something cool here — match returned a value and we stored it in name. That's because match is an expression in Rust, not just a statement.

Matching ranges

Instead of listing every number, you can match a whole range using ..= (inclusive range):

let score = 72;

let grade = match score {
    90..=100 => "A",   // matches 90, 91, 92 ... 100
    80..=89  => "B",
    70..=79  => "C",
    60..=69  => "D",
    _        => "F",
};

println!("Your grade is: {}", grade);
// Output: Your grade is: C

💡 90..=100 means "90 to 100, including both endpoints". The = in ..= makes it inclusive.

Matching enums — the most common use

This is where match truly shines. Rust enums can have different variants, and match is the natural way to handle each one.

enum Direction {
    North,
    South,
    East,
    West,
}

let heading = Direction::North;

let message = match heading {
    Direction::North => "Going up!",
    Direction::South => "Going down!",
    Direction::East  => "Going right!",
    Direction::West  => "Going left!",
    // No _ needed — all 4 variants are covered!
};

println!("{}", message);
// Output: Going up!

When you cover every enum variant, no catch-all is needed. And if you add a new variant later (say, NorthEast), Rust will immediately tell you everywhere in your code that you forgot to handle it.

Destructuring — unpacking values from enums

Enum variants can hold data. With match, you can unpack that data right in the pattern. This is called destructuring.

enum Message {
    Hello(String),   // holds a String
    Number(i32),     // holds an i32
    Quit,            // holds nothing
}

let msg = Message::Hello(String::from("Rustacean"));

match msg {
    Message::Hello(name) => println!("Hello, {}!", name),
    Message::Number(n)   => println!("Got number: {}", n),
    Message::Quit        => println!("Quit!"),
}
// Output: Hello, Rustacean!

Message::Hello(name) both matches the variant and pulls out the inner String into a variable called name. One line does two things!

Matching `Option<T>`

Option is one of Rust's most important types. It represents a value that might or might not exist — either Some(value) or None. You'll use match with it all the time.

fn find_first_even(numbers: Vec<i32>) -> Option<i32> {
    for n in numbers {
        if n % 2 == 0 {
            return Some(n);  // found one!
        }
    }
    None  // nothing found
}

let result = find_first_even(vec![1, 3, 4, 7]);

match result {
    Some(n) => println!("First even number: {}", n),
    None    => println!("No even numbers found."),
}
// Output: First even number: 4

Matching `Result<T, E>` — handling errors

Result is how Rust handles errors. A function that can fail returns either Ok(value) for success or Err(reason) for failure. match is the standard way to handle both cases.

Example 1 — password check

fn check_password(input: &str) -> Result<&str, &str> {
    if input == "secret123" {
        Ok("Access granted")
    } else {
        Err("Wrong password")
    }
}

fn main() {
    match check_password("secret123") {
        Ok(msg)  => println!("{}", msg),
        Err(err) => println!("{}", err),
    }
}
// Output: Access granted

The Result<&str, &str> return type means: "this function returns either a success &str or an error &str". The match handles both cases and unpacks the inner value.

Example 2 — safe division

fn divide(a: i32, b: i32) -> Result<i32, String> {
    if b == 0 {
        Err("Can't divide by zero".to_string())
    } else {
        Ok(a / b)
    }
}

fn main() {
    let result = divide(10, 0);

    match result {
        Ok(value) => println!("Result is {}", value),
        Err(err)  => println!("Error: {}", err),
    }
}
// Output: Error: Can't divide by zero

Since b is 0, the function returns Err(...), and our match catches it cleanly. No crashes, no panics!

💡 Option vs Result:

Use Option when a value might not exist.

Use Result when an operation can fail and you want to explain why.

`match` vs `if/else` — when to use which

Situation	Use	Why
Checking many specific values	`match`	Cleaner and exhaustive
Handling `Option` or `Result`	`match`	Unpacks values naturally
Simple true/false condition	`if/else`	More readable for one condition
Comparing with `>`, `<`	`if/else`	`match` doesn't support these directly
Matching enum variants	`match`	Compiler verifies all variants covered

Quick summary

Here's everything match gives you:

Patterns & arms — each pattern => code pair is an arm; Rust tries them top to bottom
Exhaustive — every possible value must be covered, or your code won't compile
Returns a value — you can write let x = match ... to capture the result
Destructuring — unpack data from inside enum variants right in the pattern

What to try next

Write a function that returns Result<i32, String> and handle it with match
Look into if let — a shorthand for when you only care about one pattern
Explore Option methods like .unwrap_or() and .map() — they use match under the hood

That's it! match might feel different at first if you're coming from other languages, but once it clicks, you'll wonder how you ever lived without it. 🦀

Found this helpful? Drop a ❤️ or share it with someone learning Rust!

JWT Auth Middleware in Axum 0.8 — A Beginner's Guide

Syeed Talha — Sun, 26 Apr 2026 17:09:13 +0000

If you've ever built a web API, you've probably asked yourself: "How do I make sure only the right people can access certain routes?" That's exactly what authentication middleware solves — and in this guide, you'll learn how to do it in Axum 0.8 using JSON Web Tokens (JWT).

By the end of this article, you'll understand:

What JWTs are and why they're useful
How middleware works in Axum 0.8
How to write a JWT auth middleware from scratch
How to protect routes and pass user data to your handlers

Let's get started.

What is a JWT?

A JSON Web Token (JWT) is a compact, self-contained string that carries information about a user. It looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0IiwiZXhwIjoxNzAwMDAwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

It has three parts separated by dots:

Header — the algorithm used to sign the token (e.g. HS256)
Payload — the actual data (e.g. user ID, expiry time)
Signature — proves the token hasn't been tampered with

Here's the flow: a user logs in → your server creates a JWT and sends it back → the user includes that JWT in future requests → your middleware validates it before the request reaches your handler.

What is Middleware in Axum?

Think of middleware as a security guard standing between the internet and your handlers. Every request passes through the guard first. The guard can:

Let the request through (valid token → call next.run(req))
Block the request (invalid or missing token → return 401 Unauthorized)
Attach extra information to the request (e.g. the logged-in user's ID)

In Axum 0.8, you write middleware as a plain async function and wrap it with middleware::from_fn().

Project Setup

Start by creating a new project:

cargo new axum-jwt-demo
cd axum-jwt-demo

Add these dependencies to your Cargo.toml:

[dependencies]
axum       = "0.8"
tokio      = { version = "1", features = ["full"] }
tower      = "0.5"
jsonwebtoken = { version = "10.3.0", features = ["rust_crypto"] }
serde      = { version = "1", features = ["derive"] }
serde_json = "1"

Here's what each crate does:

axum — the web framework
tokio — the async runtime axum runs on
tower — the middleware system axum uses under the hood
jsonwebtoken — encode and decode JWTs
serde / serde_json — serialize and deserialize the JWT payload (called "claims")

Step 1 — Define Your JWT Claims

A JWT's payload is called claims. Claims are just a Rust struct that you serialize into the token. At a minimum you want a user ID and an expiry time.

Create src/claims.rs:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct Claims {
    pub sub: String,   // subject — usually the user ID
    pub exp: usize,    // expiry timestamp (Unix time)
}

The field names sub and exp are standard JWT claim names. exp is especially important — the jsonwebtoken crate automatically rejects tokens where exp is in the past.

Step 2 — Create Helper Functions

You need two helpers: one to create a JWT (for your login route), and one to validate a JWT (for your middleware).

Create src/auth.rs:

use jsonwebtoken::{decode, encode, DecodingKey, EncodingKey, Header, Validation};
use std::time::{SystemTime, UNIX_EPOCH};

use crate::claims::Claims;

// In a real app, store this in an environment variable — never hardcode it!
const SECRET: &[u8] = b"my-super-secret-key";

/// Create a JWT for a given user ID.
/// Returns the token string on success.
pub fn create_token(user_id: &str) -> Result<String, jsonwebtoken::errors::Error> {
    let expiry = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_secs() as usize
        + 3600; // token expires in 1 hour

    let claims = Claims {
        sub: user_id.to_string(),
        exp: expiry,
    };

    encode(
        &Header::default(),
        &claims,
        &EncodingKey::from_secret(SECRET),
    )
}

/// Validate a JWT string.
/// Returns the decoded Claims on success, or an error if the token is invalid/expired.
pub fn validate_token(token: &str) -> Result<Claims, jsonwebtoken::errors::Error> {
    let token_data = decode::<Claims>(
        token,
        &DecodingKey::from_secret(SECRET),
        &Validation::default(),
    )?;

    Ok(token_data.claims)
}

Quick note on the secret key: In production, never hardcode this. Load it from an environment variable using the dotenvy crate. Anyone who knows the secret can forge tokens.

&[u8] in Simple Terms

Think of it as a peek at some bytes — you're looking, not touching.

The pieces:

u8 → a number from 0–255 (one byte)
[u8] → a list of those numbers
& → "I'm just looking at it, not owning it"

The most common use:

let key: &[u8] = b"hello";

b"hello" just means "give me the raw numbers behind this text" → [104, 101, 108, 108, 111]

String vs Bytes — one line:

let a = "ABC";    // text
let b = b"ABC";   // same thing, but as numbers: [65, 66, 67]

One-line summary:
&[u8] = "borrowed list of numbers" — you're pointing at bytes, not storing them.

Now lets understand `encode(...)` — What Each Argument Does

encode(
        &Header::default(),
        &claims,
        &EncodingKey::from_secret(SECRET),
    )

This line creates the actual JWT token. Think of it as:

"Pack my data, sign it with a key, and give me a token string."

&Header::default()
The token format settings — just use defaults (algorithm: HS256).
Like saying "standard packaging, nothing special."

&claims
The actual data you want to store in the token — the user ID + expiry time.
This is the "what's inside the box."

&EncodingKey::from_secret(SECRET)
Your secret key used to sign the token, so nobody can fake it.
Like a wax seal on a letter — if it's broken, you know it was tampered with.
Now why the & on everything?
Just means "borrow it, don't consume it" — same & you already learned.

Full picture in one line:

encode( how to pack it,  what to pack,  your secret stamp )
       └─ Header ──────┘ └─ Claims ──┘ └─ EncodingKey ───┘

Now lets understand `validate_token` Simply

    let token_data = decode::<Claims>(
        token,
        &DecodingKey::from_secret(SECRET),
        &Validation::default(),
    )?;
    Ok(token_data.claims)

This function checks if a token is real and trustworthy, then pulls out the data inside.

decode::<Claims>(...)
Open the token and try to read it as Claims (user ID + expiry).
The <Claims> part just says "I expect this type inside."

token
The raw JWT string the user sent you — "here's the token, check it."

&DecodingKey::from_secret(SECRET)
Your secret key to verify the signature.
Like checking the wax seal — "did I actually stamp this, or did someone fake it?"

&Validation::default()
The rules to check against — expiry time, algorithm, etc.
Like saying "run the standard checks, nothing custom."

? at the end
If anything fails (fake token, expired, wrong key) — stop and return the error immediately.

Ok(token_data.claims)
Everything passed ✅ — return just the useful part (user ID + expiry), not the whole token object.

Full picture:

decode( the token,  your secret key,   the rules )
        └─ input ─┘ └─ verify seal ──┘ └─ checks ┘
             ↓
        token_data.claims  →  just give me the data inside

Step 3 — Write the Auth Middleware

Now for the heart of this guide — the middleware function.

Create src/middleware.rs:

use axum::{
    extract::Request,
    http::{header, StatusCode},
    middleware::Next,
    response::Response,
};

use crate::auth::validate_token;
use crate::claims::Claims;

pub async fn jwt_auth(
    mut req: Request,
    next: Next,
) -> Result<Response, StatusCode> {

    // 1. Get the Authorization header
    let auth_header = req
        .headers()
        .get(header::AUTHORIZATION)
        .and_then(|value| value.to_str().ok());

    // 2. Make sure it starts with "Bearer "
    let token = match auth_header {
        Some(header) if header.starts_with("Bearer ") => {
            &header["Bearer ".len()..] // slice off "Bearer " prefix
        }
        _ => {
            // No token or wrong format — reject with 401
            return Err(StatusCode::UNAUTHORIZED);
        }
    };

    // 3. Validate the token
    match validate_token(token) {
        Ok(claims) => {
            // 4. Attach the claims to the request so handlers can use them
            req.extensions_mut().insert(claims);
            // 5. Pass the request to the next layer (your handler)
            Ok(next.run(req).await)
        }
        Err(_) => {
            // Invalid or expired token — reject with 401
            Err(StatusCode::UNAUTHORIZED)
        }
    }
}

Let's walk through what happens:

The middleware reads the Authorization header from the incoming request.
It checks that the header starts with "Bearer " — the standard format for JWT tokens.
It calls validate_token() to verify the signature and check the expiry.
If valid, it inserts the decoded Claims into the request's extensions — a type-safe bag you can attach extra data to.
It calls next.run(req) to pass the request onward to your handler.
If anything fails, it immediately returns a 401 Unauthorized response. The handler never runs.

Lets understand the `Auth Header` — Simply Explained

    let auth_header = req 
        .headers()
        .get(header::AUTHORIZATION)
        .and_then(|v| v.to_str().ok());

This code looks for the Authorization header in the request — like checking if someone showed their ID card.

req.headers()
Get all headers from the incoming request.
Like "open the envelope and look at the labels."

A real request might carry headers like:

Authorization: Bearer eyJ...   // who you are (token)
Content-Type: application/json // what format the body is in
Accept-Language: en-US         // what language you prefer
User-Agent: Mozilla/5.0        // what browser/app you're using

All of these live inside .headers() — a map of key → value pairs.

.get(header::AUTHORIZATION)
Find specifically the Authorization header.
Like "do you have an ID card?"

There are many header types you could .get() instead:

.get(header::CONTENT_TYPE)     // "what format is the body?"
.get(header::USER_AGENT)       // "what app sent this?"
.get(header::ACCEPT_LANGUAGE)  // "what language does the user want?"

Returns Some(value) if found, None if missing. ✅ / ❌

.and_then(|v| v.to_str().ok())
If the header exists, try to convert it to a readable string.

and_then → "if it exists, do this next step"
to_str().ok() → convert bytes to text, or return None if it fails

let auth_header
The result is either:

Some("Bearer eyJ...") → token found ✅
None → no header, no token ❌

Full picture:

req.headers()          // all headers
  .get(AUTHORIZATION)  // find the auth one
  .and_then(...)        // if found → convert to string
                              ↓
                 Some("Bearer eyJ...") or None

Lets understand the Extracting the Token — Simply Explained

let token = match auth_header {
        Some(header) if header.starts_with("Bearer ") => {
            &header["Bearer ".len()..]
        }
        _=>{
            return Err(StatusCode::UNAUTHORIZED);
        }
    };

This code pulls out the actual token from the header value — like "ok you have an ID card, now let me read what's on it."

match auth_header
Check what's inside auth_header — like an if/else but cleaner.

Some(header) if header.starts_with("Bearer ")
Two checks in one line:

Some(header) → the header actually exists
if header.starts_with("Bearer ") → it looks like a real auth header

A valid header looks like this:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
                ↑
           this part is the format we expect

If both checks pass → go ahead ✅

&header["Bearer ".len()..]
Cut off the "Bearer " part and keep only the token.

"Bearer eyJhbGci..."
         ↑
         start here → "eyJhbGci..."

"Bearer ".len() → the length of "Bearer " which is 7
[7..] → "give me everything after position 7"

_ => return Err(StatusCode::UNAUTHORIZED)
_ means everything else — no header, wrong format, anything unexpected.
Just say "401 Unauthorized, go away."

Full picture:

match auth_header
  ├── exists + starts with "Bearer " → strip it → just the token ✅
  └── anything else                  → 401 Unauthorized ❌

Lets understand the Token validation part

match validate_token(token) {
        Ok(claims) => {
            // 4. Attach the claims to the request so handlers can use them
            req.extensions_mut().insert(claims);
            // 5. Pass the request to the next layer (your handler)
            Ok(next.run(req).await)
        }
        Err(_) => {
            // Invalid or expired token — reject with 401
            Err(StatusCode::UNAUTHORIZED)
        }
    }

This code checks if the token is real, then either lets the request through or blocks it.

match validate_token(token)
Run the token through the validator we saw earlier.
Returns either Ok(claims) or Err(...) — "valid or not?"

Ok(claims) =>
Token is valid ✅ — now do two things:

req.extensions_mut().insert(claims)
Attach the user's data (claims) to the request.
Like "staple the user's ID info to the envelope" so any handler down the line can read it without checking the token again.

request  →  [token checked ✅]  →  claims attached  →  handler can use it

Ok(next.run(req).await)
Pass the request forward to the actual handler.

next → "whoever is waiting for this request"
.run(req) → "send it through"
.await → "wait for it to finish"

Like a security guard who checked your ID and now says "ok, you can go in." 🚪✅

Err(_) => Err(StatusCode::UNAUTHORIZED)
Token is fake, expired, or broken ❌
_ means "I don't care what the error is" — just reject with 401.

Full picture:

validate_token(token)
  ├── Ok  → attach claims to request → pass to handler ✅
  └── Err → 401 Unauthorized ❌

Step 4 — Write the Handlers

Now write a login handler (issues the token) and a protected handler (requires the token).

Create src/handlers.rs:

use axum::{extract::Extension, http::StatusCode, response::Json};
use serde_json::{json, Value};

use crate::auth::create_token;
use crate::claims::Claims;

/// Public route — anyone can call this to get a token.
pub async fn login() -> Result<Json<Value>, StatusCode> {
    // In a real app: verify username/password from the request body first!
    let user_id = "user-42";

    match create_token(user_id) {
        Ok(token) => Ok(Json(json!({ "token": token }))),
        Err(_) => Err(StatusCode::INTERNAL_SERVER_ERROR),
    }
}

/// Protected route — only accessible with a valid JWT.
pub async fn dashboard(
    Extension(claims): Extension<Claims>,
) -> Json<Value> {
    // `claims` was attached by the middleware — no manual extraction needed
    Json(json!({
        "message": "Welcome to your dashboard!",
        "user_id": claims.sub,
    }))
}

Notice how dashboard receives Extension(claims): Extension<Claims> — it's able to read the claims that the middleware attached to the request, without doing any JWT work itself. The middleware and handler are cleanly separated.

Lets understand the `Extension(claims): Extension<Claims>`

This is how the handler grabs the user's data that the middleware stapled to the request earlier.

The whole thing is just a function argument:

pub async fn dashboard(
    Extension(claims): Extension<Claims>,  // ← this is just one argument
)

Axum automatically reads the request and fills this in for you. No manual work needed.

Extension<Claims> — the type
"I want to extract an Extension that contains Claims from the request."
Like saying "I know there's a stamped ID card on this envelope, give it to me."

Extension(claims) — the pattern
Unwrap the Extension wrapper and give me just the inner value as claims.

Think of it like a gift box:

Extension( claims )
└─ the box ─┘└─ what's inside ─┘

You don't care about the box — you just want what's inside. ✅

Together:

Extension(claims): Extension<Claims>
//    ↑                   ↑
// unwrap it,         expect this type
// call it `claims`   in the request

Why no manual extraction?
Because middleware already did the hard work:

middleware → validate token → insert(claims) → attached to request
handler   → Extension(claims)               → just grab it, done ✅

Step 5 — Wire Everything Together

Finally, set up the router in src/main.rs:

mod auth;
mod claims;
mod handlers;
mod middleware;

use axum::{middleware as axum_middleware, routing::get, Router};
use handlers::{dashboard, login};
use middleware::jwt_auth;

#[tokio::main]
async fn main() {
    // Protected routes — JWT middleware runs before each handler
    let protected = Router::new()
        .route("/dashboard", get(dashboard))
        .route_layer(axum_middleware::from_fn(jwt_auth));

    // Public routes — no middleware
    let app = Router::new()
        .route("/login", get(login))
        .merge(protected);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    println!("Listening on http://localhost:3000");
    axum::serve(listener, app).await.unwrap();
}

Two important things here:

route_layer() applies the middleware only to the routes defined above it in protected. The /login route is completely unaffected.
layer() (if used on the whole router) would apply the middleware to every route — including /login and even 404 responses. Use route_layer when you want surgical control.

Step 6 — Try It Out

Run the server:

cargo run

Get a token (hit the login route):

curl http://localhost:3000/login
# Response: {"token":"eyJhbGci..."}

Access the protected route with the token:

curl -H "Authorization: Bearer eyJhbGci..." http://localhost:3000/dashboard
# Response: {"message":"Welcome to your dashboard!","user_id":"user-42"}

Try without a token:

curl http://localhost:3000/dashboard
# Response: 401 Unauthorized

Try with a fake token:

curl -H "Authorization: Bearer fake-token" http://localhost:3000/dashboard
# Response: 401 Unauthorized

Everything works exactly as expected.

Common Mistakes to Avoid

Hardcoding the secret key. Use environment variables in production. The dotenvy crate makes this easy — load your secret with std::env::var("JWT_SECRET") at startup.

Forgetting the expiry claim. If you don't set exp, anyone who gets hold of a token can use it forever. Always set a reasonable expiry (1 hour is a common choice for access tokens).

Using layer() instead of route_layer(). This accidentally protects your login route too, creating a chicken-and-egg problem where users can't log in because they need a token to get a token.

Not returning the right HTTP status codes. Use 401 Unauthorized when the token is missing or invalid. Use 403 Forbidden if the token is valid but the user doesn't have permission for that specific resource.

What's Next?

Now that you have the basics working, here are some natural next steps:

Refresh tokens — issue a short-lived access token and a long-lived refresh token so users stay logged in without re-entering their password.
Role-based access control — add a role field to your Claims struct and check it in the middleware or handler to differentiate between admin and regular users.
The governor crate — pair your auth middleware with rate limiting to protect your login route from brute-force attacks.
Secure your secret — use dotenvy to load JWT_SECRET from a .env file and never commit secrets to version control.

Authentication is one of those things that feels complex at first but clicks once you see the full picture. You've now got a solid foundation to build on.

Axum Middleware Explained for Absolute Beginners (With Full Code)

Syeed Talha — Wed, 22 Apr 2026 02:46:03 +0000

Middleware in Axum often looks scary—not because it’s hard, but because the code syntax feels unfamiliar.

This guide explains everything in a very simple, beginner-friendly way, including:

Full working code
Cargo.toml setup
Clear explanation of the confusing parts

🧠 What is Middleware?

Middleware is just a function that runs:

before your handler
after your handler

Think of it like a wrapper around your route.

📦 Step 1: Cargo.toml Setup

Create a new Rust project and add this:

[dependencies]
axum = "0.7"
tokio = { version = "1", features = ["full"] }
tracing = "0.1"
tracing-subscriber = "0.3"

💻 Step 2: Full Working Code

use axum::{
    routing::get,
    Router,
    middleware,
    extract::Request,
    response::Response,
};

use tracing::info;
use std::time::Instant;
use tokio::time::{sleep, Duration};

async fn handler() -> &'static str {
    sleep(Duration::from_secs(2)).await;
    "Hello world from Axum"
}

async fn my_middleware(
    req: Request<axum::body::Body>,
    next: middleware::Next,
) -> Response {

    println!("-> Before handler");

    let start = Instant::now();

    let res = next.run(req).await;

    println!("<- After handler");
    println!("Time: {:?}", start.elapsed());

    res
}

#[tokio::main]
async fn main() {

    tracing_subscriber::fmt::init();

    let app = Router::new()
        .route("/", get(handler))
        .layer(middleware::from_fn(my_middleware));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    info!("Server running on http://0.0.0.0:3000");

    axum::serve(listener, app).await.unwrap();
}

🚀 What Happens When You Run This?

You visit http://localhost:3000
Middleware runs before
Handler runs (waits 2 seconds)
Middleware runs after
Response is sent

Console output:

-> Before handler
<- After handler
Time: 2.00s

🔥 Now Let’s Explain the Confusing Parts

This is the most important section.

1️⃣ `req: Request<axum::body::Body>`

req: Request<axum::body::Body>

What is this?

This is the incoming HTTP request.

It contains:

URL (/)
headers
body (data sent by client)

Why is it written like this?

Rust is very strict about types, so it says:

Request<T> → request with some body type
axum::body::Body → the actual body format

👉 Simple meaning:

“This is the full request coming from the client”

You can just think:

req = user request

2️⃣ `next: middleware::Next`

next: middleware::Next

What is this?

This represents the next step in the chain.

That could be:

your handler
or another middleware

Simple meaning:

“What should happen after this middleware?”

3️⃣ The MOST IMPORTANT Line

let res = next.run(req).await;

What is happening here?

This line says:

“Send the request forward and wait for the response”

Break it down:

Part	Meaning
`next.run(...)`	call the next step
`req`	pass the request
`.await`	wait for result
`res`	store the response

Why is this REQUIRED?

Without this line:

the handler will never run
the request will stop inside middleware

👉 Middleware must always decide:

forward request ❓
or block it ❌

4️⃣ `tracing_subscriber::fmt::init();`

tracing_subscriber::fmt::init();

What is this?

This sets up logging system.

Why do we need it?

Because this line alone does nothing:

info!("Server running...");

Rust logging works like this:

tracing → creates logs
tracing-subscriber → displays logs

Without init():

logs are silently ignored ❌

With init():

logs are printed to console ✅

5️⃣ `info!`

info!("Server running on http://0.0.0.0:3000");

What is this?

This is a log message, like println! but better.

Why use it instead of `println!`?

Because it supports:

log levels (info, debug, error)
filtering
structured logging

👉 Example:

RUST_LOG=debug cargo run

⚡ Quick Comparison

Feature	println!	info!
Works instantly	✅	❌ (needs init)
Log levels	❌	✅
Production use	❌	✅

🎯 Final Mental Model

Whenever you see middleware, think:

1. Receive request
2. Do something BEFORE
3. Call next.run(req)
4. Do something AFTER
5. Return response

🏁 Summary

req → the incoming request
next → what happens next
next.run(req).await → pass control forward
tracing_subscriber::fmt::init() → enable logging
info! → structured logging

Middleware is not complex — it just looks complex.

Once you understand the flow, everything becomes simple.

If you want to go further, next steps could be:

Authentication middleware
Logging every request
Error handling middleware

Just continue building — that’s the best way to learn 🚀

Axum Middleware: A Beginner's Complete Guide

Syeed Talha — Sun, 19 Apr 2026 17:42:21 +0000

If you are learning Axum and the word middleware makes your brain freeze — this guide is for you. We will go from zero to writing real working middleware, one small step at a time.

Updated for Axum 0.8.x — the latest stable version. If you have seen other tutorials using axum::http::Request or axum = "0.7", those are outdated. This guide uses the correct current patterns straight from the official docs.

1. What is Middleware?

Here is the plain-English definition:

Middleware is code that runs between the moment a request arrives at your server and the moment your handler function deals with it.

The Restaurant Analogy

Imagine your web server is a restaurant. Every customer (HTTP request) who walks in goes through several steps before the chef (your handler) cooks their food:

The doorman checks they are on the guest list → Auth middleware
The host writes their name in the log book → Logging middleware
The waiter checks they have not ordered too much already → Rate-limit middleware
Finally the chef cooks the meal → Your handler function

Middleware is those steps between the door and the kitchen.

// Without middleware
Client  ──────────────────────────────>  Handler

// With middleware
Client  ->  Logger  ->  Auth  ->  Handler
        <-          <-        <-
        (response flows back the same way)

The key insight: middleware runs on the way IN (before handler) and also on the way OUT (after handler). One piece of code, two chances to do work.

2. Why Do We Need Middleware?

Imagine you have 20 routes in your app. Every route needs to check if the user is logged in. Without middleware, you would write the same auth check 20 times — once inside each handler. That is a nightmare to maintain.

Middleware solves this by letting you write that logic once and apply it to all routes automatically. Common uses:

Logging — record every request: method, path, time taken, status code
Authentication — verify the user's token before they can access protected routes
Rate limiting — prevent one user from flooding your server with requests
CORS headers — allow browsers from other domains to talk to your API
Compression — automatically gzip response bodies to save bandwidth
Request ID — stamp every request with a unique ID for debugging

3. How Axum Does Middleware

Axum is built on top of a library called Tower. Tower has a concept called a Layer — a wrapper around your app that intercepts requests. Middleware in Axum is a Tower layer.

The good news: you do not need to understand Tower internals. Axum gives you a helper called from_fn that lets you write a plain async function:

use axum::middleware::from_fn;

// Your middleware is just an async fn
async fn my_middleware(req: Request, next: Next) -> Response {
    // ... your logic here
}

// Attach it with .layer()
let app = Router::new()
    .route("/hello", get(handler))
    .layer(from_fn(my_middleware));

💡 from_fn is the magic adapter. You write a normal async function, and from_fn converts it into the Tower layer format that Axum expects. Always use from_fn as a beginner — the alternative is implementing Tower traits manually, which is much harder.

4. The Correct Imports (Axum 0.8)

This is where many beginners hit their first compiler error. Request is a generic type — it needs a body type parameter — so you cannot just write use axum::http::Request and move on.

Axum 0.8 ships a pre-aliased version that already has the body type filled in. Always import Request from axum::extract:

// ✅ CORRECT — pre-aliased, body type already filled in for you
use axum::extract::Request;
use axum::middleware::Next;
use axum::response::Response;

// ❌ WRONG — this is the raw generic, compiler will complain
use axum::http::Request;

The full import block you will use for almost every middleware file:

use axum::{
    extract::Request,            // ← axum::extract, NOT axum::http
    middleware::{from_fn, Next},
    http::{StatusCode, header},  // header gives you header::AUTHORIZATION etc.
    response::{Response, IntoResponse},
};

5. Understanding the Function Signature

With the right imports in place, let us break down the function shape piece by piece.

async fn my_middleware(
    req: Request,
    next: Next,
) -> Response {
    // body
}

`async fn`

async fn means this is an asynchronous function. All network code in Rust must be async because waiting for a network response without async would freeze the whole server. Every Axum middleware must be async — no exceptions.

`req: Request`

req is the incoming HTTP request — the axum::extract::Request alias you imported above. Through it you can read:

req.method()      // GET, POST, PUT, DELETE, etc.
req.uri()         // the URL path like /users or /profile
req.headers()     // all HTTP headers: Authorization, Content-Type, etc.
req.extensions()  // extra data that other middleware has attached

`next: Next`

next represents everything that comes after this middleware — the next middleware in the stack and eventually your handler. Think of it as a "proceed" button.

You call next.run(req).await to pass the request forward. If you never call it, the request stops at your middleware — useful for rejecting bad tokens early.

`-> Response`

Your middleware must always return a Response. There are exactly two ways this happens:

// Way 1: let the handler produce a response
let response = next.run(req).await;
response

// Way 2: reject early, build your own response
return (StatusCode::UNAUTHORIZED, "bad token").into_response();
// next.run() is never called — handler never runs

6. What Goes Inside the Body

The body of your middleware is split into two zones by the next.run() call:

use axum::{extract::Request, middleware::Next, response::Response};

async fn my_middleware(req: Request, next: Next) -> Response {

    // ── ZONE 1: runs BEFORE your handler ──────────────────
    // Inspect or modify the request here
    println!("→ incoming: {} {}", req.method(), req.uri());

    let response = next.run(req).await;  // <-- THE PIVOT POINT

    // ── ZONE 2: runs AFTER your handler ───────────────────
    // Inspect or modify the response here
    println!("← outgoing: {}", response.status());

    response  // always return a response
}

📌 The pivot point: next.run(req).await is the most important line in any middleware. Everything before it runs on the request (way in). Everything after it runs on the response (way out). You do not have to use both zones — many middlewares only do work before next.run, and just return the response unchanged.

7. Logging Requests

There are two approaches: the easy way using tower-http, and the manual way writing your own.

The Easy Way: TraceLayer

The tower-http crate ships a ready-made logging middleware. First, update Cargo.toml:

[dependencies]
axum        = "0.8"
tokio       = { version = "1", features = ["full"] }
tower-http  = { version = "0.6", features = ["trace"] }
tracing     = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

Then in main.rs:

use axum::{routing::get, Json, Router};
use tower_http::trace::TraceLayer;
use tracing::info;
use tracing_subscriber::EnvFilter;

async fn get_users() -> Json<Vec<String>> {
    info!("Handling get_users request");
    Json(vec!["Alice".to_string(), "Bob".to_string()])
}

#[tokio::main]
async fn main() {
    // Set up tracing with env-filter
    // Default: show info from our crate + trace from tower_http
    tracing_subscriber::fmt()
        .with_env_filter(
            EnvFilter::try_from_default_env()
                .unwrap_or_else(|_| EnvFilter::new("axum_tracing_example=info,tower_http=trace")),
        )
        .init();

    let app = Router::new()
        .route("/users", get(get_users))
        .layer(TraceLayer::new_for_http());

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    info!("Server running on http://0.0.0.0:3000");
    axum::serve(listener, app).await.unwrap();
}

When a request comes in you will see this automatically:

2026-04-21T02:26:04.777002Z DEBUG request{method=GET uri=/users version=HTTP/1.1}: tower_http::trace::on_request: started processing request
2026-04-21T02:26:04.777296Z DEBUG request{method=GET uri=/users version=HTTP/1.1}: tower_http::trace::on_response: finished processing request latency=0 ms status=200

The Manual Way: Writing Your Own Logger

Sometimes you want full control over the log format:

use axum::{extract::Request, middleware::Next, response::Response};
use std::time::Instant;

async fn logger(req: Request, next: Next) -> Response {
    let method = req.method().clone();
    let uri    = req.uri().clone();
    let start  = Instant::now();

    // call next and get the response
    let response = next.run(req).await;

    // now we have the status code and elapsed time
    println!(
        "{} {} {} {}ms",
        method, uri,
        response.status(),
        start.elapsed().as_millis()
    );
    // prints: GET /users 200 OK 4ms

    response
}

8. Writing Auth Middleware

Auth middleware is the most common custom middleware you will write. The official Axum docs recommend returning Result<Response, StatusCode> — this is cleaner than calling .into_response() manually everywhere, and it is what you will see in real industry code.

use axum::{
    extract::Request,
    http::{StatusCode, header},
    middleware::Next,
    response::Response,
};

async fn require_auth(req: Request, next: Next) -> Result<Response, StatusCode> {
    // Use header:: constants — cleaner than raw strings like "authorization"
    let auth_header = req
        .headers()
        .get(header::AUTHORIZATION)           // ← header::AUTHORIZATION constant
        .and_then(|v| v.to_str().ok())
        .ok_or(StatusCode::UNAUTHORIZED)?;    // ← ? bails out early if missing

    if auth_header == "Bearer my-secret-token" {
        Ok(next.run(req).await)               // ← wrap in Ok()
    } else {
        Err(StatusCode::UNAUTHORIZED)         // ← return Err to reject
    }
}

💡 Why Result<Response, StatusCode>? It lets you use the ? operator to bail out early on missing or invalid values, which reads much more naturally than nested match blocks. Axum knows how to convert a StatusCode error into an HTTP response automatically.

`.layer()` vs `.route_layer()`

The official Axum docs distinguish two ways to attach middleware, and this matters for auth:

// .layer() — wraps EVERYTHING: your routes AND the 404 fallback handler
let app = Router::new()
    .route("/private", get(private_handler))
    .layer(from_fn(require_auth));

// .route_layer() — wraps only your defined routes, NOT the fallback
// This is what the official docs recommend for auth middleware
let app = Router::new()
    .route("/private", get(private_handler))
    .route_layer(from_fn(require_auth));

For auth middleware, prefer .route_layer(). If someone hits a non-existent URL, the 404 is returned without ever touching your auth logic — which is usually the right behaviour.

9. Stacking Multiple Middlewares

You can add as many .layer() calls as you want. They wrap each other like layers of an onion.

let app = Router::new()
    .route("/dashboard", get(dashboard))
    .route_layer(from_fn(require_auth))  // runs 2nd
    .layer(from_fn(logger));             // runs 1st (outermost = listed last)

⚠️ Layer order gotcha: The last .layer() you write is the outermost one, meaning it runs first on incoming requests. Last written = outermost = runs first.

Visually the stack looks like this:

Request comes in
     |
     v
[ logger middleware ]           <- outermost, runs first
  [ require_auth middleware ]   <- inner, runs second
    [ your handler ]            <- innermost, runs last
  [ require_auth middleware ]   <- on the way back out
[ logger middleware ]           <- on the way back out
     |
     v
Response goes out

10. A Complete Working Example

Here is a full Axum 0.8 server you can copy, paste, and run:

# Cargo.toml
[dependencies]
axum               = "0.8"
tokio              = { version = "1", features = ["full"] }
serde              = { version = "1", features = ["derive"] }
tower-http         = { version = "0.6", features = ["trace"] }
tracing-subscriber = "0.3"

use axum::{
    extract::Request,
    http::{StatusCode, header},
    middleware::{self, Next},
    response::{Json, Response},
    routing::get,
    Router,
};
use serde::Serialize;
use std::time::Instant;
use tower_http::trace::TraceLayer;

// ── Middleware 1: Logger ────────────────────────────────────────────
async fn logger(req: Request, next: Next) -> Response {
    let method = req.method().clone();
    let uri    = req.uri().clone();
    let start  = Instant::now();

    let response = next.run(req).await;

    println!(
        "{} {} → {} ({}ms)",
        method, uri,
        response.status(),
        start.elapsed().as_millis()
    );
    response
}

// ── Middleware 2: Auth ──────────────────────────────────────────────
async fn require_auth(req: Request, next: Next) -> Result<Response, StatusCode> {
    let token = req
        .headers()
        .get(header::AUTHORIZATION)
        .and_then(|v| v.to_str().ok())
        .ok_or(StatusCode::UNAUTHORIZED)?;

    if token == "Bearer secret123" {
        Ok(next.run(req).await)
    } else {
        Err(StatusCode::UNAUTHORIZED)
    }
}

// ── Handlers ────────────────────────────────────────────────────────
#[derive(Serialize)]
struct Message { text: String }

async fn public_route() -> Json<Message> {
    Json(Message { text: "Anyone can see this".to_string() })
}

async fn private_route() -> Json<Message> {
    Json(Message { text: "You are authenticated!".to_string() })
}

// ── Main ────────────────────────────────────────────────────────────
#[tokio::main]
async fn main() {
    tracing_subscriber::fmt::init();

    let app = Router::new()
        .route("/public",  get(public_route))
        .route("/private", get(private_route))
        .route_layer(middleware::from_fn(require_auth)) // auth: route-level only
        .layer(middleware::from_fn(logger))             // logger: global
        .layer(TraceLayer::new_for_http());             // structured tracing on top

    println!("Server running on http://localhost:3000");
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Test it with curl:

# Public route — works without a token
curl http://localhost:3000/public

# Private route without token → 401
curl http://localhost:3000/private

# Private route with valid token → 200
curl -H "Authorization: Bearer secret123" http://localhost:3000/private

11. Common Beginner Mistakes

Mistake 1: Wrong `Request` import

// ❌ WRONG — generic type, compiler error in Axum 0.8
use axum::http::Request;

// ✅ CORRECT — pre-aliased with body type baked in
use axum::extract::Request;

Mistake 2: The Semicolon Trap

// ❌ WRONG — semicolon drops the value, nothing is returned
async fn my_middleware(req: Request, next: Next) -> Response {
    next.run(req).await;  // ← this semicolon is the bug!
}

// ✅ CORRECT — no semicolon, last expression is returned
async fn my_middleware(req: Request, next: Next) -> Response {
    next.run(req).await   // ← no semicolon = this value is returned
}

Mistake 3: Moving `req` Before You Are Done With It

// ❌ WRONG — Rust's borrow checker will stop you
async fn my_middleware(req: Request, next: Next) -> Response {
    let method = req.method();           // borrows req
    let response = next.run(req).await;  // moves req — compiler error!
    println!("{}", method);
    response
}

// ✅ CORRECT — clone what you need before moving req
async fn my_middleware(req: Request, next: Next) -> Response {
    let method = req.method().clone();   // clone it first
    let response = next.run(req).await;  // now safe to move
    println!("{}", method);
    response
}

Mistake 4: Wrong Layer Order

// ❌ WRONG — if you want logger to run before auth:
let app = Router::new()
    .route("/", get(handler))
    .layer(from_fn(logger))  // you think this runs first...
    .layer(from_fn(auth));   // but this actually runs first!

// ✅ CORRECT — last listed = outermost = runs first
let app = Router::new()
    .route("/", get(handler))
    .layer(from_fn(auth))    // runs second
    .layer(from_fn(logger)); // runs first

12. Quick Reference

You want to…	Use this
Import `Request` correctly	`use axum::extract::Request`
Log all requests easily	`TraceLayer::new_for_http()` from `tower-http 0.6`
Write custom middleware	`from_fn(your_async_fn)`
Read request method	`req.method().clone()`
Read request path	`req.uri().clone()`
Read the Authorization header	`req.headers().get(header::AUTHORIZATION)`
Pass request to handler	`next.run(req).await`
Reject early (`-> Response`)	`return (StatusCode::UNAUTHORIZED, "msg").into_response()`
Reject early (`-> Result`)	`return Err(StatusCode::UNAUTHORIZED)`
Wrap specific routes only	`.route_layer(from_fn(...))`
Wrap everything including fallback	`.layer(from_fn(...))`

Summary

Middleware is code that runs between a request arriving and your handler running
use axum::extract::Request — always import from here in Axum 0.8, never from axum::http
from_fn turns your plain async fn into a middleware layer — always use it as a beginner
-> Result<Response, StatusCode> is the idiomatic return type for auth middleware per the official docs
header::AUTHORIZATION — use the typed constant, not the raw string "authorization"
next: Next is the proceed button — call next.run(req).await to pass the request forward
Zone 1 / Zone 2 — code before next.run() runs on the way in; code after runs on the way out
.route_layer() wraps only your routes; .layer() wraps everything including the 404 fallback
Layer order — the last .layer() you write is the outermost one, so it runs first

What to Try Next

Now that you understand middleware, try these in order:

Add TraceLayer to a real project and watch the logs appear in your terminal
Write a middleware that adds a custom response header (hint: response.headers_mut())
Learn about State — the recommended way to share app-wide data like a database pool
Explore tower-http 0.6 for ready-made middleware like CorsLayer and CompressionLayer

Found this helpful? Drop a ❤️ and share it with someone learning Rust. Happy coding! 🦀

Implementing POST and GET in Axum using in-memory storage.

Syeed Talha — Tue, 14 Apr 2026 10:26:10 +0000

Step 1 — Create the project

cargo new axum-demo
cd axum-demo

Add dependencies to Cargo.toml:

[dependencies]
axum = "0.7"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"

Step 2 — The full `main.rs`

use axum::{
    extract::State,
    http::StatusCode,
    routing::{get, post},
    Json, Router,
};
use serde::{Deserialize, Serialize};
use std::sync::{Arc, Mutex};

// ── 1. Data model ──────────────────────────────────────────────────────────────
// In FastAPI you'd write:
//   class User(BaseModel):
//       id: int
//       name: str
//       email: str
//
// In Rust we derive Serialize (→ JSON output) and Deserialize (← JSON input)

#[derive(Debug, Serialize, Deserialize, Clone)]
struct User {
    id: u32,
    name: String,
    email: String,
}

// Only these fields are required when CREATING a user (no id yet)
// FastAPI equivalent: class CreateUser(BaseModel): name: str; email: str
#[derive(Debug, Deserialize)]
struct CreateUser {
    name: String,
    email: String,
}

// ── 2. Shared in-memory state ──────────────────────────────────────────────────
// Arc  = shared ownership across threads (like Python's threading.Lock wrapper)
// Mutex= only one thread can write at a time
// Vec  = growable list (like Python's list)
type AppState = Arc<Mutex<Vec<User>>>;

// ── 3. Handlers ───────────────────────────────────────────────────────────────

// POST /users
// FastAPI equivalent:
//   @app.post("/users", status_code=201)
//   def create_user(body: CreateUser):
//       ...
async fn create_user(
    State(state): State<AppState>,   // Axum injects shared state automatically
    Json(body): Json<CreateUser>,    // Axum parses the JSON body automatically
) -> (StatusCode, Json<User>) {
    let mut users = state.lock().unwrap(); // lock the Mutex to get write access

    let new_user = User {
        id: users.len() as u32 + 1,  // simple auto-increment
        name: body.name,
        email: body.email,
    };

    users.push(new_user.clone());

    (StatusCode::CREATED, Json(new_user)) // returns 201 + the created user as JSON
}

// GET /users
// FastAPI equivalent:
//   @app.get("/users")
//   def list_users():
//       ...
async fn list_users(
    State(state): State<AppState>,
) -> Json<Vec<User>> {
    let users = state.lock().unwrap(); // lock for read access
    Json(users.clone())                // return a copy as JSON
}

// ── 4. main — wire everything together ────────────────────────────────────────
#[tokio::main]  // like: if __name__ == "__main__": uvicorn.run(app)
async fn main() {
    let state: AppState = Arc::new(Mutex::new(vec![])); // start with empty list

    let app = Router::new()
        .route("/users", post(create_user)) // POST /users → create_user handler
        .route("/users", get(list_users))   // GET  /users → list_users handler
        .with_state(state);                 // attach shared state to all routes

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    println!("Server running on http://localhost:3000");
    axum::serve(listener, app).await.unwrap();
}

Step 3 — Run and test

cargo run

Create a user:

curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# Response: {"id":1,"name":"Alice","email":"alice@example.com"}

List all users:

curl http://localhost:3000/users

# Response: [{"id":1,"name":"Alice","email":"alice@example.com"}]

Key concepts to remember

🔹 `Debug`

Lets you print the struct in a developer‑friendly way using println!("{:?}", user).
Without it, you can’t easily inspect values during debugging.

🔹 `Serialize`

Comes from Serde.
Allows you to convert your struct into JSON (or other formats).
Example: turn User { id: 1, name: "Alice".to_string(), email: "a@b.com".to_string() } into:

  {
    "id": 1,
    "name": "Alice",
    "email": "a@b.com"
  }

🔹 `Deserialize`

Also from Serde.
Allows you to take JSON (or other formats) and build your struct back.
Example: given the JSON above, Serde can create a User struct automatically.

🔹 `Clone`

Lets you make a copy of the struct.
Example:

  let user1 = User { id: 1, name: "Alice".to_string(), email: "a@b.com".to_string() };
  let user2 = user1.clone(); // now user2 is a copy of user1

Without Clone, you couldn’t duplicate the struct this way.

Why all together?

Debug → for printing and debugging.
Serialize + Deserialize → for JSON in/out (essential in web APIs).
Clone → for copying values when needed.

So this combination makes your User struct easy to debug, send/receive as JSON, and duplicate safely.

Now lets understand Arc<Mutex<Vec<User>>> & State(...)

`Arc<Mutex<Vec<User>>>` — The shared notebook

Imagine you run a small shop. You have one notebook where you write down customer names.

Now imagine multiple cashiers (= multiple request handlers running at the same time). They all need to read and write that same notebook.

Two problems arise:

Problem 1 — Who owns the notebook?
In Rust, every value has exactly one owner. But you need all cashiers to share it. Arc solves this — think of it as a photocopy machine that gives everyone a pointer to the same original notebook. Nobody owns it exclusively; everyone just holds a reference.

Arc = shared ownership across threads. When the last cashier is done, it auto-deletes.

Problem 2 — Two cashiers writing at the same time = chaos
If cashier A and cashier B both write at the exact same millisecond, the notebook gets corrupted. Mutex solves this — think of it as a physical lock on the notebook cabinet. Only one cashier can open it at a time. Others wait.

Mutex = take a lock, do your work, release the lock

So the full picture:

Arc         <  Mutex      <  Vec<User>  >>
"shared"       "one at       "the actual
 pointer"       a time"       notebook"

In Python you almost never think about this because Python's GIL handles it behind the scenes. In Rust, you are explicit about it — which makes it safer.

`State(...)` — The magic backpack

When your server starts, you create the notebook (the Vec) and put it in a backpack:

let state = Arc::new(Mutex::new(vec![]));

let app = Router::new()
    .route("/users", post(create_user))
    .with_state(state);  // 👈 put it in the backpack

Now every incoming request automatically carries that backpack. When a handler wants the notebook, it just asks for it:

async fn create_user(
    State(state): State<AppState>,  // 👈 "give me what's in the backpack"
    Json(body): Json<CreateUser>,
) { ... }

Axum sees State(AppState) in the function signature and says "oh, this handler needs the shared state — let me inject it automatically."

FastAPI comparison:

# FastAPI — you use Depends() to inject shared things
def get_db():
    return fake_db

@app.post("/users")
def create_user(body: CreateUser, db=Depends(get_db)):
    #                              ^^^^^^^^^^^^^^^^
    #                              FastAPI injects this

// Axum — you use State(...) to inject shared things
async fn create_user(
    State(state): State<AppState>,  // Axum injects this
    Json(body): Json<CreateUser>,
) { ... }

Same idea — the framework injects a shared dependency into your function. The syntax is just different.

One more thing — why does Rust force you to think about this?

In Python, you write:

users = []  # global list, everyone just uses it

@app.post("/users")
def create_user(body: CreateUser):
    users.append(...)  # just works, Python handles safety behind the scenes

Python hides the complexity. Rust makes you say it out loud:

// "This is a list, shared across threads, protected by a lock"
let state: Arc<Mutex<Vec<User>>> = Arc::new(Mutex::new(vec![]));

It feels verbose at first, but this is exactly why Rust programs don't have race conditions — you cannot accidentally share data unsafely. The compiler won't let you.

So we can say, Arc<Mutex<Vec<User>>> is the "database" for now. Arc lets multiple request handlers share the same data. Mutex ensures only one handler writes at a time — without it, two simultaneous POST requests could corrupt the list.

State(...) — Axum automatically injects the shared state into any handler that asks for it. In FastAPI you'd use Depends() for something similar.

Json(...) does double duty — as an extractor in function parameters (parses incoming JSON) and as a response type in the return value (serializes to JSON output).

(StatusCode, Json<T>) as a return type is how you return both a status code and a body. Returning just Json<T> implicitly gives a 200 OK.

Thank you for reading ^_^

Beginner’s Guide to Axum: Path, Query & JSON

Syeed Talha — Tue, 14 Apr 2026 05:58:35 +0000

If you're starting backend development in Rust, Axum is a great choice.

In this guide, we will build a small API and learn:

✅ Path Parameters
✅ Query Parameters
✅ JSON Request & Response

And most importantly: you’ll get the FULL working code at the end.

What We Are Building

We will create 3 routes:

Route	Method	Description
`/user/:name/:id/:age`	GET	Path parameters
`/search?name=...&age=...`	GET	Query parameters
`/user`	POST	JSON request

Required Dependencies

We use serde for converting data.

Add this to your Cargo.toml:

[dependencies]
axum = "0.7"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }

1. Path Parameters

Example URL

/user/talha/10/22

👉 Here:

name = talha
id = 10
age = 22

Code

async fn get_user(Path((name, id, age)): Path<(String, i32, i32)>) -> String {
    format!("User Name is: {}\n, age: {}\n and Id is {}", name, age, id)
}

Axum extracts values directly from the URL.

2. Query Parameters

Example URL

/search?name=talha&age=22

Struct

#[derive(Deserialize)]
struct SearchParams {
    name: String,
    age: i32,
}

Code

async fn search(Query(params): Query<SearchParams>) -> String {
    format!("User name is {} and he is now {} years old", params.name, params.age)
}

Axum converts query into a struct automatically.

3. JSON Request & Response (POST)

Request JSON

{
  "name": "Talha",
  "age": 22
}

Structs

#[derive(Deserialize)]
struct CreateUser {
    name: String,
    age: i32,
}

#[derive(Serialize)]
struct UserResponse {
    message: String,
}

Code

async fn create_user(Json(payload): Json<CreateUser>) -> Json<UserResponse> {
    let msg = format!("User {} is {} years old", payload.name, payload.age);

    Json(UserResponse {
        message: msg,
    })
}

Full Working Code (Copy & Run)

This is the complete code you can copy and run directly:

use axum::{
    routing::{get, post},
    Router,
    extract::{Path, Query, Json},
};
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct SearchParams {
    name: String,
    age: i32,
}

#[derive(Deserialize)]
struct CreateUser {
    name: String,
    age: i32,
}

#[derive(Serialize)]
struct UserResponse {
    message: String,
}

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/user/:name/:id/:age", get(get_user))
        .route("/search", get(search))
        .route("/user", post(create_user));

    let addr = "127.0.0.1:3000";
    println!("Server running on http://{}", addr);

    axum::serve(
        tokio::net::TcpListener::bind(addr).await.unwrap(),
        app,
    )
    .await
    .unwrap();
}

async fn get_user(Path((name, id, age)): Path<(String, i32, i32)>) -> String {
    format!("User Name is: {}\n, age: {}\n and Id is {}", name, age, id)
}

async fn search(Query(params): Query<SearchParams>) -> String {
    format!(
        "User name is {} and he is now {} years old",
        params.name, params.age
    )
}

async fn create_user(Json(payload): Json<CreateUser>) -> Json<UserResponse> {
    let msg = format!("User {} is {} years old", payload.name, payload.age);

    Json(UserResponse {
        message: msg,
    })
}

How to Run

cargo run

Then test in browser or Postman:

Test Path

http://localhost:3000/user/talha/10/22

Test Query

http://localhost:3000/search?name=talha&age=22

Test POST (Important)

Use Postman / curl:

curl -X POST http://localhost:3000/user \
-H "Content-Type: application/json" \
-d '{"name":"Talha","age":22}'

What You Learned

✔ Path parameters → Path<T>
✔ Query parameters → Query<T>
✔ JSON body → Json<T>
✔ Structs + Serde = powerful API

Understand Your First Axum Server by Comparing with FastAPI

Syeed Talha — Sun, 12 Apr 2026 18:42:15 +0000

If you're coming from Python and have used FastAPI, learning Rust’s Axum can feel confusing at first. But the good news is: the core ideas are almost the same.

Let’s break down this simple Axum server step by step and compare it with FastAPI so it clicks instantly.

🧩 The Full Code

use axum::{ routing::get, Router, };
use std::net::SocketAddr;

#[tokio::main]
async fn main() {
    // 1. Create a route
    let app = Router::new()
        .route("/", get(root));

    // 2. Define address
    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));

    println!("Server running at http://{}", addr);

    // 3. Run server
    let listener = tokio::net::TcpListener::bind(addr).await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

// 4. Handler function
async fn root() -> &'static str {
    "Hello, Axum! Hello guys how are you!!!"
}

🧠 Big Picture

This program does 4 simple things:

Create a web app
Define a route (/)
Start a server on 127.0.0.1:3000
Return a response when someone visits

🔹 Step 1: Importing Things

use axum::{ routing::get, Router };
use std::net::SocketAddr;

What this means:

Bring Router → to create the app
Bring get → to define GET routes
Bring SocketAddr → to define IP + port

🐍 FastAPI equivalent:

from fastapi import FastAPI

🔹 Step 2: Async Main Function

#[tokio::main]
async fn main() {

What this means:

Rust normally doesn’t support async in main, so we use Tokio (an async runtime).

👉 This is like saying:

“Run this program using async engine”

🐍 FastAPI equivalent:

import asyncio

async def main():
    ...

asyncio.run(main())

🔹 Step 3: Create the App

let app = Router::new()
    .route("/", get(root));

What this means:

Create a new app (Router::new())
Add a route /
When someone sends a GET request, call root

🐍 FastAPI equivalent:

app = FastAPI()

@app.get("/")
async def root():
    return "Hello"

👉 Same idea, different syntax.

🔹 Step 4: Define Address

let addr = SocketAddr::from(([127, 0, 0, 1], 3000));

What this means:

Your server will run on:

http://127.0.0.1:3000

🐍 FastAPI equivalent:

uvicorn.run(app, host="127.0.0.1", port=3000)

🔹 Step 5: Bind the Server

let listener = tokio::net::TcpListener::bind(addr).await.unwrap();

What this means:

Open port 3000
Start listening for incoming requests

Think of it like:

“Open the door and wait for visitors”

🐍 Python equivalent:

server.bind(("127.0.0.1", 3000))
server.listen()

🔹 Step 6: Start the Server

axum::serve(listener, app).await.unwrap();

What this means:

Take incoming requests from listener
Pass them to your app (Router)
Run forever

🐍 FastAPI equivalent:

uvicorn.run(app)

🔹 Step 7: Handler Function

async fn root() -> &'static str {
    "Hello, Axum! Hello guys how are you!!!"
}

What this means:

When someone visits /, this function runs and returns a response.

🐍 FastAPI equivalent:

@app.get("/")
async def root():
    return "Hello, Axum!"

🔁 Full Request Flow

Here’s what happens when you open your browser:

Browser → http://127.0.0.1:3000/
        ↓
TcpListener (listening)
        ↓
Axum Server
        ↓
Router matches "/"
        ↓
root() function runs
        ↓
Response sent back

Now Full fastapi code:

from fastapi import FastAPI
import uvicorn

# 1. Create app
app = FastAPI()

# 2. Create route
@app.get("/")
async def root():
    return "Hello, Axum! Hello guys how are you!!!"

# 3. Run server
if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=3000)

🔹 Key Difference (important)

👉 In Axum (Rust):

You manually:
bind address
create listener
start server

👉 In FastAPI (Python):

uvicorn.run() does everything for you

Simple Mental Model

Concept	Axum	FastAPI
App	`Router::new()`	`FastAPI()`
Route	`.route("/", get(...))`	`@app.get("/")`
Handler	`async fn root()`	`async def root()`
Server start	`axum::serve(...)`	`uvicorn.run()`
Address	`SocketAddr`	host + port

Final Summary

This whole Axum program means:

“Create a web server that listens on port 3000, and when someone visits /, return a simple message.”

If you're already comfortable with FastAPI, you're much closer to mastering Axum than you think. The concepts are the same — Rust just makes things more explicit and safe.

DEV Community: Syeed Talha

CRUD API in Rust Using Axum, SQLite, and sqlx

What We Are Using

Project Structure

Step 1: Add Dependencies

Step 2: Create state.rs

Explanation

Step 3: Create models.rs

Explanation

Why Serialize?

Why Deserialize?

Why FromRow?

Step 4: Create db.rs

Explanation

Step 5: Create handlers.rs

Understanding the Handlers

State(state): State<AppState>

Json(payload): Json<CreateUser>

Path(id): Path<i64>

.bind()

fetch_one

fetch_all

fetch_optional

Step 6: Create main.rs

Understanding main.rs

Step 7: Run the Server

Step 8: Test the API

Create User

Get All Users

Get One User

Update User

Delete User

Why We Did Not Put Everything in main.rs

Current Limitations

Final Thoughts

Sharing Data in Axum State, Arc, Mutex & RwLock

The Problem: Handlers Don't Share Memory by Default

Tool #1 — Arc<T>: Shared Ownership Across Threads

Tool #2 — State<T>: Axum's Dependency Injection

Tool #3 — Mutex<T>: Exclusive Access for Writes

Tool #4 — RwLock<T>: Many Readers, One Writer

std::sync vs tokio::sync — Which Should You Use?

Choosing the Right Tool

A Complete Working Example

Cargo.toml

main.rs

Common Gotchas

❌ Forgetting .with_state()

❌ Using Rc<T> instead of Arc<T>

❌ Holding std::sync::Mutex across .await

❌ RwLock write starvation

Quick Reference Cheatsheet

Summary

Error Handling in Axum

The Core Idea: Errors Must Become Responses

1. The Simplest Error: Return a StatusCode

2. Returning Richer Errors with Tuples

3. Building a Custom Error Type (The Right Way)

4. Returning JSON Errors

5. Converting ? Errors with From

6. Using anyhow for Quick Prototyping

7. Handler-Level Error Handling with HandleError

Quick Reference

Summary

Build In-Memory CRUD API in Axum (Rust)

What We Will Build

Step 1: Setup Dependencies

Step 2: Define Our Data

Step 3: App State (In-Memory Database)

Step 4: Create User (POST)

Step 5: Get All Users (GET)

Step 6: Get Single User

Step 7: Update User

Step 8: Delete User

Step 9: Setup Router & Main

Full Code (Mutex Version)

Bonus: Async RwLock Version

How to Test

Key Concepts You Learned

What's Next?

Step 2: Create `state.rs`

Step 3: Create `models.rs`

Why `Serialize`?

Why `Deserialize`?

Why `FromRow`?

Step 4: Create `db.rs`

Step 5: Create `handlers.rs`

`State(state): State<AppState>`

`Json(payload): Json<CreateUser>`

`Path(id): Path<i64>`

`.bind()`

`fetch_one`

`fetch_all`

`fetch_optional`

Step 6: Create `main.rs`

Understanding `main.rs`

Why We Did Not Put Everything in `main.rs`

Tool #1 — `Arc<T>`: Shared Ownership Across Threads

Tool #2 — `State<T>`: Axum's Dependency Injection

Tool #3 — `Mutex<T>`: Exclusive Access for Writes

Tool #4 — `RwLock<T>`: Many Readers, One Writer

`std::sync` vs `tokio::sync` — Which Should You Use?

`Cargo.toml`

`main.rs`

❌ Forgetting `.with_state()`

❌ Using `Rc<T>` instead of `Arc<T>`

❌ Holding `std::sync::Mutex` across `.await`

❌ `RwLock` write starvation

1. The Simplest Error: Return a `StatusCode`

5. Converting `?` Errors with `From`

6. Using `anyhow` for Quick Prototyping

7. Handler-Level Error Handling with `HandleError`

What is `match`?

The catch-all pattern: `_`

Matching `Option<T>`

Matching `Result<T, E>` — handling errors

`match` vs `if/else` — when to use which

Now lets understand `encode(...)` — What Each Argument Does

Now lets understand `validate_token` Simply

Lets understand the `Auth Header` — Simply Explained

Lets understand the `Extension(claims): Extension<Claims>`

1️⃣ `req: Request<axum::body::Body>`

2️⃣ `next: middleware::Next`

4️⃣ `tracing_subscriber::fmt::init();`

5️⃣ `info!`

Why use it instead of `println!`?

`async fn`

`req: Request`

`next: Next`

`-> Response`