1# axum
2
3`axum` is a web application framework that focuses on ergonomics and modularity.
4
5[![Build status](https://github.com/tokio-rs/axum/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/tokio-rs/axum/actions/workflows/CI.yml)
6[![Crates.io](https://img.shields.io/crates/v/axum)](https://crates.io/crates/axum)
7[![Documentation](https://docs.rs/axum/badge.svg)](https://docs.rs/axum)
8
9More information about this crate can be found in the [crate documentation][docs].
10
11## High level features
12
13- Route requests to handlers with a macro free API.
14- Declaratively parse requests using extractors.
15- Simple and predictable error handling model.
16- Generate responses with minimal boilerplate.
17- Take full advantage of the [`tower`] and [`tower-http`] ecosystem of
18  middleware, services, and utilities.
19
20In particular the last point is what sets `axum` apart from other frameworks.
21`axum` doesn't have its own middleware system but instead uses
22[`tower::Service`]. This means `axum` gets timeouts, tracing, compression,
23authorization, and more, for free. It also enables you to share middleware with
24applications written using [`hyper`] or [`tonic`].
25
26## Usage example
27
28```rust
29use axum::{
30    routing::{get, post},
31    http::StatusCode,
32    response::IntoResponse,
33    Json, Router,
34};
35use serde::{Deserialize, Serialize};
36use std::net::SocketAddr;
37
38#[tokio::main]
39async fn main() {
40    // initialize tracing
41    tracing_subscriber::fmt::init();
42
43    // build our application with a route
44    let app = Router::new()
45        // `GET /` goes to `root`
46        .route("/", get(root))
47        // `POST /users` goes to `create_user`
48        .route("/users", post(create_user));
49
50    // run our app with hyper
51    // `axum::Server` is a re-export of `hyper::Server`
52    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
53    tracing::debug!("listening on {}", addr);
54    axum::Server::bind(&addr)
55        .serve(app.into_make_service())
56        .await
57        .unwrap();
58}
59
60// basic handler that responds with a static string
61async fn root() -> &'static str {
62    "Hello, World!"
63}
64
65async fn create_user(
66    // this argument tells axum to parse the request body
67    // as JSON into a `CreateUser` type
68    Json(payload): Json<CreateUser>,
69) -> (StatusCode, Json<User>) {
70    // insert your application logic here
71    let user = User {
72        id: 1337,
73        username: payload.username,
74    };
75
76    // this will be converted into a JSON response
77    // with a status code of `201 Created`
78    (StatusCode::CREATED, Json(user))
79}
80
81// the input to our `create_user` handler
82#[derive(Deserialize)]
83struct CreateUser {
84    username: String,
85}
86
87// the output to our `create_user` handler
88#[derive(Serialize)]
89struct User {
90    id: u64,
91    username: String,
92}
93```
94
95You can find this [example][readme-example] as well as other example projects in
96the [example directory][examples].
97
98See the [crate documentation][docs] for way more examples.
99
100## Performance
101
102`axum` is a relatively thin layer on top of [`hyper`] and adds very little
103overhead. So `axum`'s performance is comparable to [`hyper`]. You can find
104benchmarks [here](https://github.com/programatik29/rust-web-benchmarks) and
105[here](https://web-frameworks-benchmark.netlify.app/result?l=rust).
106
107## Safety
108
109This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in
110100% safe Rust.
111
112## Minimum supported Rust version
113
114axum's MSRV is 1.63.
115
116## Examples
117
118The [examples] folder contains various examples of how to use `axum`. The
119[docs] also provide lots of code snippets and examples. For full-fledged examples, check out community-maintained [showcases] or [tutorials].
120
121## Getting Help
122
123In the `axum`'s repo we also have a [number of examples][examples] showing how
124to put everything together. Community-maintained [showcases] and [tutorials] also demonstrate how to use `axum` for real-world applications. You're also welcome to ask in the [Discord channel][chat] or open a [discussion] with your question.
125
126## Community projects
127
128See [here][ecosystem] for a list of community maintained crates and projects
129built with `axum`.
130
131## Contributing
132
133�� Thanks for your help improving the project! We are so happy to have
134you! We have a [contributing guide][contributing] to help you get involved in the
135`axum` project.
136
137## License
138
139This project is licensed under the [MIT license][license].
140
141### Contribution
142
143Unless you explicitly state otherwise, any contribution intentionally submitted
144for inclusion in `axum` by you, shall be licensed as MIT, without any
145additional terms or conditions.
146
147[readme-example]: https://github.com/tokio-rs/axum/tree/main/examples/readme
148[examples]: https://github.com/tokio-rs/axum/tree/main/examples
149[docs]: https://docs.rs/axum
150[`tower`]: https://crates.io/crates/tower
151[`hyper`]: https://crates.io/crates/hyper
152[`tower-http`]: https://crates.io/crates/tower-http
153[`tonic`]: https://crates.io/crates/tonic
154[contributing]: https://github.com/tokio-rs/axum/blob/main/CONTRIBUTING.md
155[chat]: https://discord.gg/tokio
156[discussion]: https://github.com/tokio-rs/axum/discussions/new?category=q-a
157[`tower::Service`]: https://docs.rs/tower/latest/tower/trait.Service.html
158[ecosystem]: https://github.com/tokio-rs/axum/blob/main/ECOSYSTEM.md
159[showcases]: https://github.com/tokio-rs/axum/blob/main/ECOSYSTEM.md#project-showcase
160[tutorials]: https://github.com/tokio-rs/axum/blob/main/ECOSYSTEM.md#tutorials
161[license]: https://github.com/tokio-rs/axum/blob/main/axum/LICENSE
162