APIs, authentication, and authorization — in the types.

13.1Handlers and extractors

Chapter 6 introduced the router. The piece to internalize for APIs is the extractor: a handler's parameters declare what to pull out of the request, and axum binds them — the direct analogue of ASP.NET model binding.

app.MapGet("/users/{id}",
  async (long id, Db db) =>
    await db.Find(id));

async fn get_user(
    State(db): State<Db>,        // ≈ DI
    Path(id): Path<u64>,      // ≈ [FromRoute]
) -> Result<Json<User>, ApiError> {
    Ok(Json(db.find(id).await?))
}

13.2Request bodies & validation

Bodies are plain structs that derive serde::Deserialize (serde is your System.Text.Json). For rules beyond "did it parse," the validator crate plays the role of DataAnnotations / FluentValidation.

use serde::Deserialize;
use validator::Validate;

#[derive(Deserialize, Validate)]
struct CreateUser {
    #[validate(email)]            // ≈ [EmailAddress]
    email: String,
    #[validate(length(min = 8))]   // ≈ [MinLength(8)]
    password: String,
}

async fn create_user(Json(body): Json<CreateUser>)
    -> Result<Json<User>, ApiError> {
    body.validate()?;          // 422 on failure, via the error type below
    // ...
}

13.3One error type → correct status codes

The idiomatic pattern: define an API error type and impl IntoResponse for it. Then every handler returns Result<T, ApiError>, the ? operator (ch. 4) propagates failures, and they turn into proper status codes and JSON bodies. This is your global exception handler / ProblemDetails, but as a value the compiler forces every handler to account for.

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

enum ApiError { NotFound, Unauthorized, Forbidden, Validation, Internal }

impl IntoResponse for ApiError {
    fn into_response(self) -> Response {
        let (status, msg) = match self {
            ApiError::NotFound     => (StatusCode::NOT_FOUND, "not found"),
            ApiError::Unauthorized => (StatusCode::UNAUTHORIZED, "unauthorized"),
            ApiError::Forbidden    => (StatusCode::FORBIDDEN, "forbidden"),
            ApiError::Validation   => (StatusCode::UNPROCESSABLE_ENTITY, "invalid"),
            ApiError::Internal     => (StatusCode::INTERNAL_SERVER_ERROR, "error"),
        };
        (status, Json(serde_json::json!({ "error": msg }))).into_response()
    }
}

13.4Authentication as an extractor

Here's the pattern worth stealing. Instead of a [Authorize] attribute plus reaching into HttpContext.User, you write a custom extractor that validates the credential and produces a CurrentUser. Any handler that names CurrentUser in its signature is, by construction, authenticated — the extractor must succeed before the handler body runs.

use axum::{extract::FromRequestParts, http::request::Parts};
use axum_extra::{TypedHeader, headers::{Authorization, authorization::Bearer}};
use jsonwebtoken::{decode, DecodingKey, Validation};

struct CurrentUser { id: u64, roles: Vec<String> }

impl<S: Send + Sync> FromRequestParts<S> for CurrentUser {
    type Rejection = ApiError;

    async fn from_request_parts(parts: &mut Parts, _: &S)
        -> Result<Self, ApiError> {
        let TypedHeader(Authorization(bearer)) =
            TypedHeader::<Authorization<Bearer>>::from_request_parts(parts, &())
                .await.map_err(|_| ApiError::Unauthorized)?;

        let claims = decode::<Claims>(bearer.token(), &key(), &Validation::default())
            .map_err(|_| ApiError::Unauthorized)?
            .claims;
        Ok(CurrentUser { id: claims.sub, roles: claims.roles })
    }
}

// this handler CANNOT run unauthenticated — the type guarantees it
async fn me(user: CurrentUser) -> Json<Profile> { /* ... */ }

13.5Authorization by composing extractors

Role and policy checks build on top. An AdminUser extractor wraps CurrentUser and rejects non-admins with 403. Requiring AdminUser in a handler's signature is the policy — the compile-time version of [Authorize(Roles = "Admin")].

struct AdminUser(CurrentUser);

impl<S: Send + Sync> FromRequestParts<S> for AdminUser {
    type Rejection = ApiError;
    async fn from_request_parts(parts: &mut Parts, s: &S)
        -> Result<Self, ApiError> {
        let user = CurrentUser::from_request_parts(parts, s).await?;
        if user.roles.iter().any(|r| r == "admin") {
            Ok(AdminUser(user))
        } else {
            Err(ApiError::Forbidden)
        }
    }
}

async fn delete_user(_admin: AdminUser, Path(id): Path<u64>)
    -> Result<StatusCode, ApiError> { /* ... */ }

13.6Cross-cutting middleware

For concerns that span routes — logging, CORS, compression, a blanket auth gate — use tower layers, which are the ASP.NET middleware pipeline. You already saw TraceLayer in this server's main.rs; others slot in the same way, and like the pipeline they apply outside-in.

use tower_http::{trace::TraceLayer, cors::CorsLayer};

let app = Router::new()
    .route("/api/users", get(list_users))
    .layer(CorsLayer::permissive())        // app.UseCors(...)
    .layer(TraceLayer::new_for_http());     // request logging

13.7Best practices