Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 38 ยท Getting Started

What Is Axum? Rust Web Services Overview

Meet Axum, the Rust web framework built on Tokio, Tower and Hyper: what it does, how a request flows through it, and when to choose it for an API or web service.

Axum is a web framework for Rust. You describe which URLs your service answers, you write ordinary async functions that handle them, and Axum takes care of the HTTP plumbing: parsing requests, picking the right function, turning your return value into a response and sending it back. It is maintained by the Tokio project, so it fits naturally with the rest of the async Rust world.

What makes Axum different from many frameworks is how little of its own machinery it has. Routing is a thin layer, handlers are plain functions, and almost everything else (timeouts, compression, tracing, CORS) comes from the Tower ecosystem. That keeps the framework small and means skills you learn here transfer to other Rust services. This course takes you from a first "hello" server to a tested, deployed API with a database.

About the runnable examples. The Axum crate itself cannot run in the in-page Rust runner, because that runner has only the standard library and no network access to crates.io. Every real Axum snippet in this course is shown read-only. Next to it you get a runnable stand-in written in plain Rust that demonstrates the same idea (routing tables, extractors, middleware, shared state). The stand-ins are labelled, and they say honestly what is real Axum and what is a model.

The pieces Axum is built from

Axum does not implement HTTP or async I/O itself. It sits on top of four libraries:

  • Tokio is the async runtime. It runs your async functions and handles sockets and timers.
  • Hyper is the HTTP implementation: it reads bytes from a socket and produces Request values (and writes Response values back).
  • Tower defines the Service trait, a general "request in, response out" interface, plus reusable middleware called layers.
  • http is a small crate with the shared types Request, Response, StatusCode, HeaderMap and Method.
flowchart LR
    C["Client"] --> H["Hyper<br/>(HTTP parsing)"]
    H --> T["Tower layers<br/>(middleware)"]
    T --> R["Axum Router"]
    R --> E["Extractors"]
    E --> F["Your handler fn"]
    F --> I["IntoResponse"]
    I --> C

A request travels left to right; the response comes back the same way.

A first look at real Axum

Here is a complete service. It answers GET / with text and GET /health with a small JSON value. Read it now and do not worry about every detail; the next lessons explain each line.

Rust
use axum::{routing::get, Json, Router};
use serde_json::{json, Value};

async fn index() -> &'static str {
    "Hello from Axum!"
}

async fn health() -> Json<Value> {
    Json(json!({ "status": "ok" }))
}

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/", get(index))
        .route("/health", get(health));

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

Three ideas are already visible. A Router maps paths and methods to handlers. A handler is an async fn that returns anything implementing IntoResponse (a &'static str, a Json<T>, a status code, a tuple of those...). And axum::serve connects a bound TCP listener to the router.

What a request really is

Under the framework, HTTP is just text over a TCP connection. The next example uses only the standard library: it starts a server on a loopback port, connects to it as a client and prints what travels over the wire. Axum and Hyper do exactly this, with far more care and speed.

Rust Stand-in: HTTP is text over TCP

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The request is a start line (GET /hello HTTP/1.1), some headers and an empty line. The response is a status line, headers, an empty line and the body. Everything Axum offers (routing, extractors, responses) is a comfortable way to read and write those pieces without handling bytes yourself.

Handlers as functions from request to response

The central idea of Axum is that a handler is just a function from "something extracted from the request" to "something that becomes a response". Here is that idea modelled with plain Rust types, no HTTP involved:

Rust Stand-in: a handler is a function

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Real Axum generalises this with traits: you do not write the match, the Router does; you do not convert values by hand, IntoResponse is implemented for dozens of types. You will build those pieces in later lessons.

Why choose Axum

  • Ergonomic. Handlers are normal functions. There are no macros on routes and no framework-specific base types.
  • Type-checked. Extractors and responses are verified at compile time. A handler that asks for something impossible will not compile.
  • Fast and lean. Rust, Tokio and Hyper give high throughput and low memory use with no garbage collector.
  • Ecosystem. Anything written for Tower (rate limiting, tracing, authorisation) works with Axum.
  • No unsafe in the framework. Axum forbids unsafe code in its own crate.

Trade-offs: Rust has a learning curve, compile times are longer than in dynamic languages, and compiler errors about handler traits can be long (the handlers lesson explains how to read them). If you are new to the language, work through the Rust tutorial first, especially async basics. Other ecosystems offer similar frameworks: compare Gin for Go or Fastify for Node.js.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which library does Axum rely on as its async runtime?

    Axum is maintained by the Tokio project and runs on the Tokio runtime.
  2. 2. What is the job of the Tower crate in the Axum stack?

    Tower defines Service and layers such as timeouts and tracing; Hyper does the HTTP parsing.
  3. 3. What is an Axum handler?

    Handlers are plain async functions; arguments are extractors and the return type implements IntoResponse.
  4. 4. Why does this course use stand-ins for Axum code?

    The runner only has Rust's standard library, so the real Axum code is read-only and the ideas are demonstrated with std-only models.

Summary

  • Axum is a small Rust web framework on top of Tokio, Hyper and Tower.
  • A Router maps methods and paths to handlers; handlers are async fns returning IntoResponse types.
  • HTTP itself is text over TCP; Axum hides the parsing and formatting.
  • Real Axum snippets here are read-only; stand-ins in plain Rust make the ideas runnable.

Next: Setting Up an Axum Project