Quick answer
Axum is a Rust web framework built on Tokio: you describe routes with small handler functions, and Axum turns them into a fast async HTTP server. This post builds a small orders API with three routes, lists two seeded orders, creates a third, and fixes a real 422 error when the JSON body forgets a field.
A small shop in Karachi takes orders over the phone and writes each one in a paper notebook. When a customer calls to ask where an order is, someone flips pages. A simple web API would fix that: list the orders, add a new one, fetch one by number. Rust suits that little service because the compiler catches whole classes of bugs before the code runs, and the finished binary starts fast and uses little memory. Axum turns that Rust code into a server without much ceremony. The rest of this post builds that API, with real output.
What I would check before using it
My first check is whether the team already writes Rust. Axum is a thin layer, and most of the work is still Rust: ownership, borrowing, and async code with Tokio. A team that already ships Rust will feel at home, while a team new to Rust will spend its first week fighting the compiler. If Rust is new to everyone, the Rust Explained: Memory Safety Without the Garbage Collector post is the place to start.
My second check is whether the API needs async. Axum is async-first, and every handler runs on Tokio. That suits an API that waits on databases and other services. For a script that runs once and exits, async is machinery with no payoff. The Build Your First REST API With Node.js and Express post shows the same three routes in Node.js.
My third check is how far the API needs to grow. Axum stays out of the way: routes, extractors, and shared state, with no database layer or admin panel. That suits a focused JSON API, and leaves a gap when the project needs auth and an admin screen on day one.
My fourth check is error handling. Rust makes the team decide what every failure returns: a missing order is a 404, a bad body is a 422, and the compiler refuses to let an error go unhandled. That discipline is what an API needs, though it makes the first version slower to write.
My verdict, as judgement: adopt Axum when the team writes Rust and the API answers JSON. Skip it when nobody on the team knows Rust yet. The recommendation flips the moment the API needs an admin panel and auth.
Three orders, one API, and a missing total
Three orders arrive at the same small shop. Ayesha buys a kurta and a dupatta for Rs 12,400, Bilal buys sneakers for Rs 7,800, and Hina buys a handbag and a wallet. The first two are seeded when the server starts; Hina's arrives later, through the API.
One file holds the whole server. An Order is what the API returns, a NewOrder is what a client sends, and the orders live in a vector behind a Mutex, shared through Axum state. Three handlers cover the routes: list them all, fetch one by id, or create one and return a 201.
// Shop orders API for The Practical Developer (Axum demo). // // A small online shop exposes three routes with axum and tokio: // GET /orders list every order // POST /orders create an order from a JSON body // GET /orders/{id} fetch one order by id // // Orders live in memory, behind a Mutex, so the demo needs no // database. A create request that forgets the total is rejected // with 422, because the NewOrder struct requires that field. // // Run from this folder: // cargo run (listens on http://127.0.0.1:3000) // curl http://127.0.0.1:3000/orders use axum::{ extract::{Path, State}, http::StatusCode, routing::get, Json, Router, }; use serde::{Deserialize, Serialize}; use std::{ net::SocketAddr, sync::{Arc, Mutex}, }; #[derive(Clone, Serialize)] struct Order { id: u32, customer: String, items: Vec<String>, total: u32, } #[derive(Deserialize)] struct NewOrder { customer: String, items: Vec<String>, total: u32, } type Orders = Arc<Mutex<Vec<Order>>>; async fn list_orders(State(orders): State<Orders>) -> Json<Vec<Order>> { Json(orders.lock().unwrap().clone()) } async fn get_order( State(orders): State<Orders>, Path(id): Path<u32>, ) -> Result<Json<Order>, StatusCode> { let orders = orders.lock().unwrap(); match orders.iter().find(|o| o.id == id) { Some(order) => Ok(Json(order.clone())), None => Err(StatusCode::NOT_FOUND), } } async fn create_order( State(orders): State<Orders>, Json(input): Json<NewOrder>, ) -> (StatusCode, Json<Order>) { let mut orders = orders.lock().unwrap(); let id = orders.iter().map(|o| o.id).max().unwrap_or(100) + 1; let order = Order { id, customer: input.customer, items: input.items, total: input.total, }; orders.push(order.clone()); (StatusCode::CREATED, Json(order)) } #[tokio::main] async fn main() { let orders: Orders = Arc::new(Mutex::new(vec![ Order { id: 101, customer: "Ayesha".to_string(), items: vec!["kurta".to_string(), "dupatta".to_string()], total: 12400, }, Order { id: 102, customer: "Bilal".to_string(), items: vec!["sneakers".to_string()], total: 7800, }, ])); let app = Router::new() .route("/orders", get(list_orders).post(create_order)) .route("/orders/{id}", get(get_order)) .with_state(orders); let addr = SocketAddr::from(([127, 0, 0, 1], 3000)); println!("Axum server listening on http://{addr}"); let listener = tokio::net::TcpListener::bind(addr).await.unwrap(); axum::serve(listener, app).await.unwrap(); } Here is the real output. The two seeded orders list cleanly, and then Hina's order goes wrong: the first POST forgets the total.
$ ./target/debug/shop-api Axum server listening on http://127.0.0.1:3000 $ curl -s http://127.0.0.1:3000/orders [{"id":101,"customer":"Ayesha","items":["kurta","dupatta"],"total":12400},{"id":102,"customer":"Bilal","items":["sneakers"],"total":7800}] $ curl -s -X POST http://127.0.0.1:3000/orders -H "Content-Type: application/json" -d '{"customer":"Hina","items":["handbag","wallet"]}' Failed to deserialize the JSON body into the target type: missing field `total` at line 1 column 48 HTTP status: 422 $ curl -s -X POST http://127.0.0.1:3000/orders -H "Content-Type: application/json" -d '{"customer":"Hina","items":["handbag","wallet"],"total":9600}' {"id":103,"customer":"Hina","items":["handbag","wallet"],"total":9600} HTTP status: 201 $ curl -s http://127.0.0.1:3000/orders/103 {"id":103,"customer":"Hina","items":["handbag","wallet"],"total":9600} HTTP status: 200 $ curl -s -o /dev/null -w "HTTP status: %{http_code}\n" http://127.0.0.1:3000/orders/999 HTTP status: 404 The thing that went wrong is the missing total. Axum hands the JSON body to serde, which looks for a field the struct requires, and the request is rejected with 422 before the handler runs. Nothing half-created sits in the orders list. Send the total, and the same request returns 201 with order 103. The FastAPI Explained: Python APIs at Full Speed post shows the same idea in Python, where a missing field also fails validation, and the Go Explained: Simple Code That Runs Fast post shows the same three routes in Go. If a field is optional, make it Option in the struct instead of sending a made-up number.
Common mistakes and how to fix them
First, putting the Json extractor before State in a handler. The symptom is a compile error, E0277, saying the handler trait is not satisfied. The fix is to keep State first: body extractors must come last, so Json goes after State, as create_order does.
Second, writing a route with the old :id syntax. Axum 0.8 changed captures to braces, so /orders/:id compiles and then panics at startup with "Path segments must not start with :". The fix is to write /orders/{id}, as the demo does.
Third, forgetting the Content-Type header on a POST. The symptom is a 415 response with "Expected request with Content-Type: application/json", even though the body is valid JSON. The fix is to send that header with every POST.
Fourth, locking the Mutex and then awaiting while holding it. The symptom is a server that slows down under load, because one handler holds the lock while it waits and every other request queues behind it. The fix is to copy what the handler needs out of the lock, drop the lock, and only then await.
Frequently Asked Questions
Do I need Tokio to use Axum? Yes. Axum is built on Tokio, and #[tokio::main] starts the runtime the server runs on.
How is Axum different from Actix Web? Both are fast Rust frameworks, but Axum is built on Tokio and Tower, while Actix Web runs on its own runtime.
Can Axum serve HTML as well as JSON? Yes. A handler can return Html for a page, or Json for an API response. The demo returns JSON only.
What happens when a client asks for an order that does not exist? The handler returns a 404, as the curl for order 999 showed. Returning a proper status beats a 200 with an error hidden inside the body.
Do I need a database to start with Axum? No. The demo keeps orders in a vector behind a Mutex, which is enough to learn routing and state. A database comes later, when orders must survive a restart.
What to remember
- Axum routes are small handler functions, and Tokio runs them.
- State comes before the body extractor; Json always goes last.
- Route captures use braces in Axum 0.8, /orders/{id}, not :id.
- A missing required field fails with 422 before the handler runs.
- Return proper statuses: 201 for a created order, 404 for a missing one.
Where this leaves you
Axum earns its place the day a small JSON API needs to be fast, correct, and hard to break by accident. The demo proved the three things that matter: two seeded orders listed as JSON, a bad request rejected with a 422 that named the missing field, and a fixed request creating order 103 with a 201. The compiler and the framework did the checking, not the developer's memory. Start with three routes and an in-memory list, then add a database when the orders must survive a restart. A small API that answers honestly beats a big one that guesses.
Further reading
- Axum docs, https://docs.rs/axum
- Axum docs, routing, https://docs.rs/axum/latest/axum/routing/index.html
- Tokio docs, https://tokio.rs/
- Axum examples, https://github.com/tokio-rs/axum/tree/main/examples
- Rust Explained: Memory Safety Without the Garbage Collector, https://practicaldevblog.blogspot.com/2026/10/rust-explained-memory-safety-without.html
- Build Your First REST API With Node.js and Express, https://practicaldevblog.blogspot.com/2026/10/build-your-first-rest-api-with-nodejs.html
- FastAPI Explained: Python APIs at Full Speed, https://practicaldevblog.blogspot.com/2026/10/fastapi-explained-python-apis-at-full.html
- Go Explained: Simple Code That Runs Fast, https://practicaldevblog.blogspot.com/2026/10/go-explained-simple-code-that-runs-fast.html
Waqas Shahid is a software engineer from Karachi with more than 12 years of experience, including 6+ years in engineering leadership. He writes The Practical Developer.