Extractors

use std::net::SocketAddr;

use axum::{
    Json, Router,
    extract::{ConnectInfo, MatchedPath, Path, Query, RawQuery},
    http::{HeaderMap, Method, Uri, header},
    routing::post,
};
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct NewReview {
    rating: u8,
    text: String,
}

#[derive(Deserialize)]
struct Notify {
    #[serde(default)]
    notify: bool,
}

#[derive(Serialize)]
struct Echo {
    method: String,
    uri: String,
    route: String,
    isbn: String,
    raw_query: Option<String>,
    notify: bool,
    user_agent: Option<String>,
    peer: String,
    rating: u8,
    text: String,
}

#[allow(clippy::too_many_arguments)] // eight extractors, deliberately
async fn add_review(
    method: Method,
    uri: Uri,
    matched: MatchedPath,
    ConnectInfo(peer): ConnectInfo<SocketAddr>,
    headers: HeaderMap,
    Path(isbn): Path<String>,
    RawQuery(raw_query): RawQuery,
    Query(Notify { notify }): Query<Notify>,
    Json(review): Json<NewReview>, // body extractor: last
) -> Json<Echo> {
    let user_agent = headers.get(header::USER_AGENT).and_then(|v| v.to_str().ok()).map(str::to_owned);
    Json(Echo {
        method: method.to_string(),
        uri: uri.to_string(),
        route: matched.as_str().to_owned(),
        isbn,
        raw_query,
        notify,
        user_agent,
        peer: peer.to_string(),
        rating: review.rating,
        text: review.text,
    })
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/api/v1/books/{isbn}/reviews", post(add_review));
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    // ConnectInfo needs the connection's address, so serve with connect info:
    axum::serve(listener, app.into_make_service_with_connect_info::<SocketAddr>()).await.unwrap();
}

$ curl -s -H 'content-type: application/json' -d '{"rating":5,"text":"A classic."}' \
    'localhost:3000/api/v1/books/9780441013593/reviews?notify=true' | jq
{
  "method": "POST",
  "uri": "/api/v1/books/9780441013593/reviews?notify=true",
  "route": "/api/v1/books/{isbn}/reviews",
  "isbn": "9780441013593",
  "raw_query": "notify=true",
  "notify": true,
  "user_agent": "curl/8.14.1",
  "peer": "127.0.0.1:52144",
  "rating": 5,
  "text": "A classic."
}

use axum::{Json, Router, extract::Path, routing::post};

#[axum::debug_handler]
async fn add_review(Json(text): Json<String>, Path(isbn): Path<String>) -> String {
    format!("{isbn}: {text}")
}

fn main() {
    let _app: Router = Router::new().route("/books/{isbn}/reviews", post(add_review));
    // error: `Json<_>` consumes the request body and thus must be the last argument to the handler function
    // error[E0277]: the trait bound `fn(Json<String>, Path<String>) -> ... {add_review}: Handler<_, _>` is not satisfied
}

use axum::{
    Json, Router,
    extract::{Path, rejection::JsonRejection},
    http::StatusCode,
    response::{IntoResponse, Response},
    routing::{get, post},
};
use serde::Deserialize;
use serde_json::json;

#[derive(Deserialize)]
struct NewBook {
    title: String,
    year: u16,
}

// Result: turn the rejection into a JSON error ourselves.
async fn create_book(payload: Result<Json<NewBook>, JsonRejection>) -> Response {
    match payload {
        Ok(Json(book)) => (StatusCode::CREATED, format!("created {} ({})\n", book.title, book.year)).into_response(),
        Err(rejection) => (
            rejection.status(),
            Json(json!({ "title": "Invalid request body", "status": rejection.status().as_u16(), "detail": rejection.body_text() })),
        )
            .into_response(),
    }
}

// Option: one handler for /shelves and /shelves/{n}.
async fn shelf(number: Option<Path<u32>>) -> String {
    match number {
        Some(Path(n)) => format!("shelf {n}\n"),
        None => "all shelves\n".to_owned(),
    }
}

fn app() -> Router {
    Router::new()
        .route("/api/v1/books", post(create_book))
        .route("/shelves", get(shelf))
        .route("/shelves/{n}", get(shelf))
}

#[tokio::main]
async fn main() {
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app()).await.unwrap();
}

$ curl -s -H 'content-type: application/json' -d '{"title":"Dune"}' localhost:3000/api/v1/books
{"detail":"Failed to deserialize the JSON body into the target type: missing field `year` at line 1 column 16","status":422,"title":"Invalid request body"}
$ curl -s localhost:3000/shelves/3
shelf 3

use std::collections::HashMap;

use axum::{Router, extract::Path, routing::get};
use serde::Deserialize;

// one capture: a scalar
async fn by_isbn(Path(isbn): Path<String>) -> String {
    format!("isbn {isbn}\n")
}

// several captures: a tuple, in path order
async fn review_by_index(Path((isbn, index)): Path<(String, u32)>) -> String {
    format!("review #{index} of {isbn}\n")
}

// several captures: a struct, by name
#[derive(Deserialize)]
struct LoanPath {
    member_id: u64,
    loan_id: u64,
}

async fn member_loan(Path(p): Path<LoanPath>) -> String {
    format!("loan {} of member {}\n", p.loan_id, p.member_id)
}

// any captures: a map (useful in middleware and generic handlers)
async fn any_params(Path(params): Path<HashMap<String, String>>) -> String {
    let mut keys: Vec<_> = params.into_iter().map(|(k, v)| format!("{k}={v}")).collect();
    keys.sort();
    format!("{}\n", keys.join(", "))
}

fn app() -> Router {
    Router::new()
        .route("/books/{isbn}", get(by_isbn))
        .route("/books/{isbn}/reviews/{index}", get(review_by_index))
        .route("/members/{member_id}/loans/{loan_id}", get(member_loan))
        .route("/debug/{a}/{b}", get(any_params))
}

#[tokio::main]
async fn main() {
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app()).await.unwrap();
}

use std::{fmt, str::FromStr};

use axum::{Router, extract::Query, routing::get};
use serde::{Deserialize, Deserializer, de};

#[derive(Debug, Deserialize)]
struct Filters {
    #[serde(default, deserialize_with = "empty_string_as_none")]
    author: Option<String>,
    #[serde(default, deserialize_with = "empty_string_as_none")]
    year: Option<u16>,
}

fn empty_string_as_none<'de, D, T>(de: D) -> Result<Option<T>, D::Error>
where
    D: Deserializer<'de>,
    T: FromStr,
    T::Err: fmt::Display,
{
    let opt = Option::<String>::deserialize(de)?;
    match opt.as_deref() {
        None | Some("") => Ok(None),
        Some(s) => s.parse().map(Some).map_err(de::Error::custom),
    }
}

async fn search(Query(filters): Query<Filters>) -> String {
    format!("{filters:?}\n")
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/api/v1/books", get(search));
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

$ curl -s 'localhost:3000/api/v1/books?author=&year=1965'
Filters { author: None, year: Some(1965) }
$ curl -s 'localhost:3000/api/v1/books'
Filters { author: None, year: None }