Rust for the web with axum

Why Rust on the server?

Web servers spend most of their time waiting on networks and databases, which async Rust handles very well (module 9). Rust servers use little memory, have predictable latency (no garbage-collection pauses) and catch many bugs at compile time. Several frameworks exist; axum is a popular choice, built by the tokio team on top of tokio and hyper (a fast HTTP library).

Setup

cargo new orders_api
cd orders_api
cargo add axum
cargo add tokio --features full
cargo add serde --features derive

Key ideas

A small orders API

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

#[derive(Clone, Serialize, Deserialize)]
struct Order {
    id: u32,
    item: String,
    qty: u32,
}

type Db = Arc<Mutex<Vec<Order>>>;

async fn list(State(db): State<Db>) -> Json<Vec<Order>> {
    Json(db.lock().unwrap().clone())
}

async fn get_one(State(db): State<Db>, Path(id): Path<u32>) -> Result<Json<Order>, StatusCode> {
    let orders = db.lock().unwrap();
    orders.iter().find(|o| o.id == id).cloned().map(Json).ok_or(StatusCode::NOT_FOUND)
}

async fn create(State(db): State<Db>, Json(order): Json<Order>) -> (StatusCode, Json<Order>) {
    db.lock().unwrap().push(order.clone());
    (StatusCode::CREATED, Json(order))
}

#[tokio::main]
async fn main() {
    let db: Db = Arc::new(Mutex::new(Vec::new()));
    let app = Router::new()
        .route("/orders", get(list).post(create))
        .route("/orders/{id}", get(get_one))
        .with_state(db);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Read the handlers slowly. State(db): State<Db> is a pattern that pulls the shared state out; Path(id): Path<u32> reads {id} from the URL and parses it as a number, answering 400 Bad Request automatically if it is not; Json(order): Json<Order> parses the body with serde and answers with an error status if the JSON is invalid. Your handler only runs with valid, typed data.

Trying it

cargo run
curl -X POST localhost:3000/orders -H "content-type: application/json" -d '{"id":1,"item":"thali","qty":2}'
curl localhost:3000/orders/1
curl -i localhost:3000/orders/99      # HTTP/1.1 404 Not Found

Going further

• A real database: the sqlx crate (async SQL with compile-time checked queries) or SeaORM, with a connection pool in State instead of the Vec.
• Middleware with tower and tower-http: logging, CORS, timeouts, compression.
• Errors: define an AppError that implements IntoResponse, so handlers can use ? and return proper status codes.
• Structured logs with the tracing crate.

Common mistakes

• Putting Json before other extractors: a compile error that is hard to read. Put the body extractor last.
• Using /:id with axum 0.8 (the old syntax). Use /{id}.
• Holding a std Mutex guard across an .await in a handler. Lock, copy what you need, drop the guard, then await.
• Forgetting .with_state(...) when handlers use State: a type error about the router.