api-bones

A small Rust crate with shared types for the surface every REST API re-invents — errors, pagination, health, identity propagation, auth headers, response envelopes — grounded in existing specs so you're not designing a house format:

• RFC 9457 Problem Details for errors
• IETF Health Check Response Format for health
• W3C traceparent for distributed tracing
• Cursor pagination and a small set of response envelope helpers on top

It's not a framework. It's not a runtime. It's the types — so every service in a project can speak the same wire format without inventing one.

Edition 2024, MSRV 1.85. MIT licensed. Full no_std support down to core-only.

Prior art

api-bones isn't inventing a new spec. It leans on work that already exists:

• problem-details — a focused crate for RFC 9457. Does one thing well. api-bones includes Problem types but bundles them with the rest of the surface (pagination, health, identity headers) so a service can adopt one dep for everything.
• utoipa and apistos — OpenAPI schema generation. api-bones is complementary: if your errors use api-bones types, your generated spec has consistent error shapes across every endpoint.
• JSON:API and HAL — older specs addressing overlapping problems. Great if they fit your world. If not, RFC 9457 is lighter and maps cleanly onto typical REST endpoints.

What's specific to api-bones is the opinion: one crate, bundled surface, strict types, RFC-grounded on the wire. If that opinion doesn't match yours, one of the above probably does.

Usage

[dependencies]
api-bones = "4.0"

Use cases

Consistent errors across every service

Instead of each service inventing its own 404 body, every handler returns ApiError::not_found(…) and clients always get RFC 9457 Problem Details:

use api_bones::{ApiError, ErrorCode};

fn find_booking(id: u64) -> Result<(), ApiError> {
    Err(ApiError::not_found(format!("booking {id} not found")))
}

Wire format:

{
  "type": "urn:api-bones:error:resource-not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "booking 42 not found"
}

The same shape. Every service. Every client. Always.

Pagination that works the same everywhere

Offset, cursor, or keyset — all three patterns share a consistent envelope. A consumer that knows how to page through one endpoint knows how to page through all of them.

Health checks your orchestrator already understands

LivenessResponse and ReadinessResponse implement the IETF Health Check Response Format. Kubernetes, Nomad, whatever you're running — it reads the content-type and knows what to do.

Polyglot SDK generation

Every type ships with utoipa (OpenAPI schema) and schemars (JSON Schema) support. Generate your OpenAPI spec, run your SDK generator, and the TypeScript / Python / Go client gets the same precise shapes your Rust handlers produce.

Satellite Crates

Types

Errors (error)

Implements RFC 9457 Problem Details.

ErrorCode variants and their HTTP status codes:

Health (health)

Implements the IETF Health Check Response Format. Content-Type: application/health+json.

Pagination (pagination)

Query (query)

URL Building (url)

Links (links)

Response Envelopes (response)

Identity Headers

All implement the HeaderId trait (as_str(), header_name()).

Auth (auth feature)

Common Primitives (common)

Other

Features

no_std Support

# no_std + alloc (WASM, embedded with allocator)
api-bones = { version = "4", default-features = false, features = ["alloc"] }

# pure no_std (core types only)
api-bones = { version = "4", default-features = false }

License

MIT — see LICENSE