Crate axum_api_kit 

Shared response types for Axum JSON APIs.

Provides building blocks that every Axum CRUD service needs but always re-defines from scratch:

• ApiError - a machine-readable JSON error body with code, message, and optional details, plus factory helpers that return (StatusCode, Json<ApiError>) tuples ready for use with Axum’s IntoResponse. Supports From conversions for common error types. With the optional validator feature enabled, also supports converting validator::ValidationErrors into structured field errors. With the optional sqlx feature enabled, also supports converting sqlx::Error into semantically correct HTTP status codes (404, 409, 422, 503, 500).
• ListResponse<T> - a generic offset/limit paginated collection response with data, total, limit, and offset fields.
• CursorResponse<T> - a generic cursor-based paginated collection response for large datasets or feeds, with data, next_cursor, and has_more fields.
• HealthResponse - a health-check response with status field supporting ok, degraded, and unhealthy states.

With optional feature flags enabled, the kit also provides request extractors that reject with an ApiError body on failure:

• ValidatedJson<T> (feature validator) - deserializes a JSON body and runs validator validation before the handler runs.
• Pagination and CursorPagination (feature extract) - parse limit/offset and cursor/limit query parameters into typed values, with list_response / cursor_response helpers that build the matching response type.

It also ships observability middleware:

• propagate_request_id and trace_requests (feature trace) - assign an x-request-id correlation id (extractable via RequestId) and emit a structured tracing event with method, path, status, and latency for each request.

And service-wiring helpers:

• health_routes and liveness (feature router) - a Router exposing /healthz and /readyz probes backed by HealthResponse.
• cors_allowing and cors_permissive (feature cors) - build a tower_http CorsLayer with sensible defaults.

With the openapi feature, all four response types derive utoipa::ToSchema so they can be referenced from a utoipa OpenApi document and appear in generated specs.

Quick Start

use axum::{Json, http::StatusCode, response::IntoResponse};
use axum_api_kit::{ApiError, ListResponse, CursorResponse, HealthResponse};
use serde::Serialize;

#[derive(Serialize)]
struct Item { id: String }

async fn list_items() -> impl IntoResponse {
    let items = vec![Item { id: "1".into() }];
    Json(ListResponse { data: items, total: 1, limit: 50, offset: 0 })
}

async fn feed_items(cursor: Option<String>) -> impl IntoResponse {
    let items = vec![Item { id: "1".into() }];
    CursorResponse { data: items, next_cursor: Some("abc".into()), has_more: true }
}

async fn get_item() -> impl IntoResponse {
    ApiError::not_found("item not found")
}

async fn health() -> impl IntoResponse {
    HealthResponse::ok()
}

Structs

ApiError

A machine-readable JSON error body.

CursorPagination

Cursor-based pagination parameters parsed from the query string.

CursorResponse

A cursor-based paginated collection response.

HealthResponse

A minimal health-check response body.

ListResponse

A generic paginated collection response.

Pagination

Offset/limit pagination parameters parsed from the query string.

RequestId

A request correlation id, stored in request extensions by propagate_request_id.

ValidatedJson

An Axum extractor that deserializes a JSON request body and validates it with validator.

Constants

REQUEST_ID_HEADER

The header used to carry the request correlation id: x-request-id.

Functions

cors_allowing

Build a CORS layer that allows the given origins.

cors_permissive

A permissive CORS layer (any origin, method, and header).

health_routes

Build a Router exposing /healthz (liveness) and /readyz (readiness) probes.

liveness

Liveness probe handler: always returns HealthResponse::ok.

propagate_request_id

Axum middleware that assigns a request correlation id and echoes it on the response.

trace_requests

Axum middleware that emits a structured tracing event when each request completes.