Routing, extractors, and responses

cargo new notes-api
cd notes-api

[package]
name = "notes-api"
version = "0.1.0"
edition = "2024"

[dependencies]
axum = { version = "0.8.9", features = ["macros", "multipart", "ws", "http2"] }
tokio = { version = "1", features = ["full"] }
tower = { version = "0.5", features = ["util", "timeout", "load-shed"] }
tower-http = { version = "0.6", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
futures-util = "0.3"
tokio-stream = "0.1"

[dev-dependencies]
http-body-util = "0.1"

use axum::{routing::get, Router};

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/", get(|| async { "Hello from Axum" }));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    axum::serve(listener, app).await.unwrap();
}

use axum::{
    extract::Path,
    routing::{delete, get, patch, post},
    Router,
};

let app = Router::new()
    .route("/health", get(health))
    .route("/notes", get(list_notes).post(create_note))
    .route("/notes/{id}", get(show_note).patch(update_note).delete(delete_note))
    .route("/assets/{*path}", get(asset));

async fn health() -> &'static str { "ok" }
async fn list_notes() {}
async fn create_note() {}
async fn show_note(Path(id): Path<u64>) {}
async fn update_note(Path(id): Path<u64>) {}
async fn delete_note(Path(id): Path<u64>) {}
async fn asset(Path(path): Path<String>) {}

use axum::{http::StatusCode, routing::get, Router};

fn api_routes() -> Router {
    Router::new()
        .route("/notes", get(list_notes))
        .route("/users", get(list_users))
}

let status_routes = Router::new().route("/health", get(health));

let app = Router::new()
    .nest("/api/v1", api_routes())
    .merge(status_routes)
    .fallback(|| async {
        (StatusCode::NOT_FOUND, "route not found")
    });

async fn update_note(
    State(state): State<AppState>, // request parts: does not consume body
    Path(id): Path<u64>,            // request parts
    headers: HeaderMap,              // request parts
    Json(input): Json<UpdateNote>,   // body: must be last
) -> Result<Json<Note>, AppError> {
    let note = state.notes.update(id, input).await?;
    Ok(Json(note))
}

use axum::debug_handler;

#[debug_handler]
async fn difficult_handler(
    Json(input): Json<CreateNote>,
) -> Result<Json<Note>, AppError> {
    // The macro reports why this function is not a valid Handler.
    todo!()
}

use axum::{
    extract::{Path, Query},
    http::{header::USER_AGENT, HeaderMap},
    Json,
};
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct Filters {
    page: Option<u32>,
    archived: Option<bool>,
}

#[derive(Serialize)]
struct ResultPage {
    notebook: String,
    page: u32,
    client: String,
}

async fn list_notebook(
    Path(notebook): Path<String>,
    Query(filters): Query<Filters>,
    headers: HeaderMap,
) -> Json<ResultPage> {
    let client = headers
        .get(USER_AGENT)
        .and_then(|value| value.to_str().ok())
        .unwrap_or("unknown")
        .to_owned();

    Json(ResultPage {
        notebook,
        page: filters.page.unwrap_or(1),
        client,
    })
}

use axum::{http::StatusCode, Json};
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct CreateNote {
    title: String,
    body: String,
}

#[derive(Serialize)]
struct Note {
    id: u64,
    title: String,
    body: String,
}

async fn create_note(
    Json(input): Json<CreateNote>,
) -> (StatusCode, Json<Note>) {
    let note = Note {
        id: 42,
        title: input.title,
        body: input.body,
    };
    (StatusCode::CREATED, Json(note))
}

use axum::{response::Html, Form};
use serde::Deserialize;

#[derive(Deserialize)]
struct Login {
    email: String,
    password: String,
}

async fn login(Form(input): Form<Login>) -> Html<String> {
    Html(format!("<p>Signed in as {}</p>", input.email))
}

[dependencies]
garde = { version = "0.23", features = ["derive", "email"] }
axum-valid = { version = "0.25", default-features = false, features = ["basic", "garde"] }

use axum::{http::StatusCode, Json};
use axum_valid::Garde;
use garde::Validate;
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, Validate)]
struct CreateAccount {
    #[garde(email)]
    email: String,

    #[garde(length(min = 12, max = 128))]
    password: String,

    #[garde(range(min = 13, max = 120))]
    age: u8,
}

#[derive(Serialize)]
struct CreatedAccount {
    id: u64,
    email: String,
}

async fn create_account(
    Garde(Json(input)): Garde<Json<CreateAccount>>,
) -> (StatusCode, Json<CreatedAccount>) {
    // This point is reached only when JSON parsing and every rule passed.
    (
        StatusCode::CREATED,
        Json(CreatedAccount { id: 42, email: input.email }),
    )
}

#[derive(Deserialize, Validate)]
struct Address {
    #[garde(length(min = 2, max = 80))]
    city: String,
}

#[derive(Deserialize, Validate)]
struct OrderInput {
    #[garde(dive)]
    shipping: Address,

    // The vector needs 1..=20 items; every item must be non-empty.
    #[garde(length(min = 1, max = 20), inner(length(min = 1)))]
    product_codes: Vec<String>,

    #[garde(custom(not_reserved))]
    display_name: String,
}

fn not_reserved(value: &str, _ctx: &()) -> garde::Result {
    match value.to_ascii_lowercase().as_str() {
        "admin" | "root" => Err(garde::Error::new("name is reserved")),
        _ => Ok(()),
    }
}

use axum::{
    body::Body,
    http::{header, Response, StatusCode},
    response::{AppendHeaders, Html, IntoResponse, NoContent, Redirect},
};

async fn created() -> impl IntoResponse {
    (
        StatusCode::CREATED,
        [(header::LOCATION, "/notes/42")],
        "created",
    )
}

async fn deleted() -> NoContent {
    NoContent
}

async fn moved() -> Redirect {
    Redirect::temporary("/new-location")
}

async fn page() -> Html<&'static str> {
    Html("<h1>Notes</h1>")
}

async fn repeated_headers() -> impl IntoResponse {
    (
        AppendHeaders([
            ("set-cookie", "theme=dark; Path=/"),
            ("set-cookie", "density=compact; Path=/"),
        ]),
        "preferences saved",
    )
}

async fn low_level() -> Response<Body> {
    Response::builder()
        .status(StatusCode::ACCEPTED)
        .header("x-job-id", "job-42")
        .body(Body::from("queued"))
        .unwrap()
}

use axum::{extract::State, routing::{get, post}, Json, Router};
use serde::{Deserialize, Serialize};
use std::sync::Arc;
use tokio::sync::RwLock;

#[derive(Clone)]
struct AppState {
    notes: Arc<RwLock<Vec<Note>>>,
}

#[derive(Clone, Deserialize, Serialize)]
struct Note {
    title: String,
}

async fn list(State(state): State<AppState>) -> Json<Vec<Note>> {
    let notes = state.notes.read().await;
    Json(notes.clone())
}

async fn create(
    State(state): State<AppState>,
    Json(note): Json<Note>,
) {
    state.notes.write().await.push(note);
}

let state = AppState {
    notes: Arc::new(RwLock::new(Vec::new())),
};

let app = Router::new()
    .route("/notes", get(list).post(create))
    .with_state(state);

use axum::extract::{FromRef, State};

#[derive(Clone)]
struct AppState {
    config: Config,
    database: DatabasePool,
}

#[derive(Clone)]
struct Config {
    public_url: String,
}

impl FromRef<AppState> for Config {
    fn from_ref(state: &AppState) -> Self {
        state.config.clone()
    }
}

async fn public_url(State(config): State<Config>) -> String {
    config.public_url
}

use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
    Json,
};
use serde_json::json;

enum AppError {
    NotFound,
    Validation(String),
    Internal,
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, message) = match self {
            Self::NotFound => (StatusCode::NOT_FOUND, "note not found".to_owned()),
            Self::Validation(message) => (StatusCode::UNPROCESSABLE_ENTITY, message),
            Self::Internal => {
                // Log the real internal error separately. Do not leak it.
                (StatusCode::INTERNAL_SERVER_ERROR, "internal error".to_owned())
            }
        };

        (status, Json(json!({ "error": message }))).into_response()
    }
}

async fn show_note() -> Result<Json<Note>, AppError> {
    Err(AppError::NotFound)
}

use axum::{
    extract::rejection::JsonRejection,
    http::StatusCode,
    Json,
};
use serde_json::{json, Value};

async fn create_note(
    payload: Result<Json<CreateNote>, JsonRejection>,
) -> Result<Json<Value>, (StatusCode, Json<Value>)> {
    let Json(input) = payload.map_err(|rejection| {
        (
            rejection.status(),
            Json(json!({ "error": rejection.body_text() })),
        )
    })?;

    Ok(Json(json!({ "saved": input.title })))
}

use axum::{
    error_handling::HandleErrorLayer,
    http::StatusCode,
    BoxError, Router,
};
use std::time::Duration;
use tower::ServiceBuilder;

let app = Router::new()
    // add routes first
    .layer(
        ServiceBuilder::new()
            .layer(HandleErrorLayer::new(|error: BoxError| async move {
                if error.is::<tower::timeout::error::Elapsed>() {
                    (StatusCode::REQUEST_TIMEOUT, "request timed out")
                } else {
                    (StatusCode::INTERNAL_SERVER_ERROR, "service failed")
                }
            }))
            .timeout(Duration::from_secs(10)),
    );