Axum Documentation

What Axum is

Axum is a web application framework for Rust maintained under the tokio-rs organisation. It is built on Tokio, hyper and tower, and its README lists the ideas it is built around: routing requests to handlers with a macro-free API, parsing requests declaratively with extractors, a simple and predictable error handling model, generating responses with minimal boilerplate, and using the tower and tower-http ecosystem for middleware. Axum has no middleware system of its own, so timeouts, tracing, compression, CORS and authorisation come as tower layers.

Where the documentation lives

The main documentation is on docs.rs, written as a long guide in the crate's front page and module pages: routing, handlers, extractors, responses, error handling, middleware and sharing state. The GitHub repository has an examples folder covering things like JWT authentication, SQLx with PostgreSQL, WebSockets, graceful shutdown, testing and error handling. The docs describe the current 0.8 line, where path parameters are written as /users/{id}.

Is it worth learning?

If you are building an HTTP API in Rust, Axum is a strong default: it is widely used, it is maintained by the same team as Tokio, and because it is built on tower, what you learn about middleware carries to other Rust network code. Actix Web is the other mature choice.

How to learn it

Read the routing, extractors and error handling sections first. Then build one endpoint with Path, one with Json and a State holding a SQLx pool. Write one error enum that implements IntoResponse so every handler returns the same error shape. After that, add tower-http layers for tracing, timeouts and CORS, and read the testing example to call your router in-process.

Prerequisites

Comfortable Rust (the Rust book up to traits and error handling) and a working grasp of async/await on Tokio. The Tokio tutorial's shared state chapter explains most errors beginners meet.

Free or paid?

Free and open source under the MIT licence.

What you can do after it

Build a structured REST API with typed extractors, consistent errors, shared state, middleware and in-process tests.

Common questions

Why does my handler not compile? Usually an argument that is not an extractor, a body extractor such as Json that is not last, or state that is not Clone. The docs cover #[debug_handler] for clearer errors.

Is it stable? Axum is still on 0.x versions, so read the changelog when you upgrade between minor versions.