api_bones/
lib.rs

1//! # api-bones
2//!
3//! Opinionated REST API types: errors (RFC 9457), pagination, health checks, and more.
4//!
5//! ## `no_std` support
6//!
7//! This crate is `#![no_std]` when the default `std` feature is disabled.
8//!
9//! | Features enabled         | Available types                                    |
10//! |--------------------------|-----------------------------------------------------|
11//! | *(none)*                 | Pure-`core` types: `ErrorCode`, `HealthStatus`, `PaginationParams`, `SortDirection` |
12//! | `alloc`                  | All types that use `String`/`Vec`/`Arc`             |
13//! | `std` *(default)*        | Full feature set including `HashMap`-backed types   |
14//!
15//! ```toml
16//! # no_std + alloc (WASM, embedded with allocator)
17//! api-bones = { version = "...", default-features = false, features = ["alloc"] }
18//!
19//! # pure no_std (core types only)
20//! api-bones = { version = "...", default-features = false }
21//! ```
22//!
23//! ## Core type: [`ApiError`]
24//!
25//! Every service serializes errors into [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)
26//! Problem Details format:
27//!
28//! ```json
29//! {
30//!   "type": "urn:api-bones:error:resource-not-found",
31//!   "title": "Resource Not Found",
32//!   "status": 404,
33//!   "detail": "Booking 123 not found"
34//! }
35//! ```
36//!
37//! ```rust
38//! use api_bones::{ApiError, ErrorCode};
39//!
40//! fn find_booking(id: u64) -> Result<(), ApiError> {
41//!     Err(ApiError::not_found(format!("booking {id} not found")))
42//! }
43//! ```
44//!
45//! ## Feature flags (selection)
46//!
47//! | Feature    | What it enables                                      |
48//! |------------|------------------------------------------------------|
49//! | `schemars` | [`schemars::JsonSchema`] derive on all public types  |
50//! | `utoipa`   | [`utoipa::ToSchema`] derive on all public types      |
51//!
52//! Enable `schemars` in your `Cargo.toml`:
53//!
54//! ```toml
55//! api-bones = { version = "3", features = ["schemars"] }
56//! ```
57//!
58//! ## Add as dependency
59//!
60//! ```toml
61//! [dependencies]
62//! api-bones = "3"
63//! ```
64
65#![cfg_attr(not(feature = "std"), no_std)]
66
67// When `std` is not available but `alloc` is, bring the alloc crate into scope.
68// Under `std`, the `alloc` crate is re-exported by `std` so no explicit import
69// is needed.
70#[cfg(all(not(feature = "std"), feature = "alloc"))]
71extern crate alloc;
72
73// Auth module: requires the `auth` feature (implies alloc + base64 + zeroize).
74#[cfg(feature = "auth")]
75pub mod auth;
76
77// Modules that require heap allocation (String / Vec / Arc).
78#[cfg(any(feature = "std", feature = "alloc"))]
79pub mod audit;
80#[cfg(any(feature = "std", feature = "alloc"))]
81pub mod bulk;
82#[cfg(any(feature = "std", feature = "alloc"))]
83pub mod cache;
84#[cfg(all(any(feature = "std", feature = "alloc"), feature = "uuid"))]
85pub mod correlation_id;
86#[cfg(any(feature = "std", feature = "alloc"))]
87pub mod cors;
88#[cfg(feature = "base64")]
89pub mod cursor;
90#[cfg(any(feature = "std", feature = "alloc"))]
91pub mod deprecated;
92#[cfg(any(feature = "std", feature = "alloc"))]
93pub mod etag;
94#[cfg(any(feature = "std", feature = "alloc"))]
95pub mod header_id;
96#[cfg(all(any(feature = "std", feature = "alloc"), feature = "uuid"))]
97pub mod idempotency;
98#[cfg(any(feature = "std", feature = "alloc"))]
99pub mod links;
100#[cfg(all(any(feature = "std", feature = "alloc"), feature = "uuid"))]
101pub mod org_context;
102#[cfg(all(any(feature = "std", feature = "alloc"), feature = "uuid"))]
103pub mod org_id;
104#[cfg(any(feature = "std", feature = "alloc"))]
105pub mod range;
106#[cfg(all(any(feature = "std", feature = "alloc"), feature = "uuid"))]
107pub mod request_id;
108#[cfg(any(feature = "std", feature = "alloc"))]
109pub mod response;
110#[cfg(any(feature = "std", feature = "alloc"))]
111pub mod slug;
112#[cfg(all(any(feature = "std", feature = "alloc"), feature = "uuid"))]
113pub mod traceparent;
114#[cfg(any(feature = "std", feature = "alloc"))]
115pub mod url;
116#[cfg(any(feature = "std", feature = "alloc"))]
117pub mod vary;
118pub mod version;
119
120// Modules available in all configurations; individual types inside are gated
121// where they require `alloc` or `std`.
122pub mod common;
123pub mod error;
124pub mod health;
125pub mod method;
126pub mod pagination;
127pub mod query;
128pub mod ratelimit;
129pub mod retry;
130pub mod status;
131
132#[cfg(any(feature = "std", feature = "alloc"))]
133pub mod content_type;
134
135#[cfg(feature = "http")]
136pub mod header;
137
138#[cfg(all(feature = "serde", any(feature = "std", feature = "alloc")))]
139pub mod serde;
140
141#[cfg(feature = "fake")]
142mod fake_impls;
143
144#[cfg(feature = "icalendar")]
145pub mod calendar;
146
147// OpenAPI helpers: Example<T> and DeprecatedField (issues #119, #120).
148pub mod openapi;
149
150pub mod has_id;
151pub use has_id::HasId;
152
153// Axum extractors beyond IntoResponse (issue #121).
154#[cfg(feature = "axum")]
155pub mod axum_extractors;
156
157#[cfg(any(feature = "std", feature = "alloc"))]
158pub use audit::{
159    AuditInfo, DeviceLease, DeviceLeaseKind, Principal, PrincipalId, PrincipalKind,
160    PrincipalParseError, ResolvedPrincipal,
161};
162#[cfg(feature = "auth")]
163pub use auth::{
164    ApiKeyCredentials, AuthScheme, AuthorizationHeader, BasicCredentials, BearerToken, OAuth2Token,
165    ParseAuthorizationError, ParsePermissionError, ParseScopeError, Permission, Scope,
166};
167#[cfg(any(feature = "std", feature = "alloc"))]
168pub use bulk::{BulkItemResult, BulkRequest, BulkResponse};
169#[cfg(feature = "uuid")]
170pub use common::ResourceId;
171#[cfg(feature = "uuid")]
172pub use common::new_resource_id;
173#[cfg(feature = "chrono")]
174pub use common::parse_timestamp;
175// Timestamp is chrono::DateTime when chrono is on (no alloc needed),
176// or String when chrono is off (needs alloc or std).
177#[cfg(any(feature = "std", feature = "alloc"))]
178pub use cache::CacheControl;
179#[cfg(any(feature = "chrono", feature = "std", feature = "alloc"))]
180pub use common::Timestamp;
181#[cfg(any(feature = "std", feature = "alloc"))]
182pub use content_type::ContentType;
183#[cfg(all(any(feature = "std", feature = "alloc"), feature = "uuid"))]
184pub use correlation_id::{CorrelationId, CorrelationIdError};
185#[cfg(any(feature = "std", feature = "alloc"))]
186pub use cors::{CorsHeaders, CorsOrigin};
187#[cfg(feature = "base64")]
188pub use cursor::{Cursor, CursorError};
189#[cfg(any(feature = "std", feature = "alloc"))]
190pub use deprecated::Deprecated;
191pub use error::ErrorCode;
192#[cfg(any(feature = "std", feature = "alloc"))]
193pub use error::ErrorTypeMode;
194#[cfg(any(feature = "std", feature = "alloc"))]
195pub use error::HttpError;
196#[cfg(all(any(feature = "std", feature = "alloc"), feature = "serde"))]
197pub use error::ProblemJson;
198#[cfg(any(feature = "std", feature = "alloc"))]
199pub use error::{ApiError, ValidationError};
200#[cfg(feature = "std")]
201pub use error::{error_type_mode, set_error_type_mode, urn_namespace};
202#[cfg(any(feature = "std", feature = "alloc"))]
203pub use etag::{ETag, IfMatch, IfNoneMatch};
204#[cfg(feature = "http")]
205pub use header::{HeaderName, HeaderValue};
206#[cfg(any(feature = "std", feature = "alloc"))]
207pub use header_id::HeaderId;
208pub use health::HealthStatus;
209#[cfg(feature = "std")]
210pub use health::ReadinessResponse;
211#[cfg(any(feature = "std", feature = "alloc"))]
212pub use health::{HealthCheck, LivenessResponse};
213#[cfg(all(any(feature = "std", feature = "alloc"), feature = "uuid"))]
214pub use idempotency::{IdempotencyKey, IdempotencyKeyError};
215#[cfg(any(feature = "std", feature = "alloc"))]
216pub use links::{Link, Links};
217pub use method::HttpMethod;
218#[cfg(all(any(feature = "std", feature = "alloc"), feature = "uuid"))]
219pub use org_context::{
220    Attestation, AttestationKind, OrganizationContext, Role, RoleBinding, RoleScope,
221};
222#[cfg(all(
223    any(feature = "std", feature = "alloc"),
224    feature = "uuid",
225    feature = "http"
226))]
227pub use org_id::OrgIdHeaderError;
228#[cfg(all(any(feature = "std", feature = "alloc"), feature = "uuid"))]
229pub use org_id::{OrgId, OrgIdError, OrgPath};
230pub use pagination::PaginationParams;
231#[cfg(any(feature = "std", feature = "alloc"))]
232pub use pagination::{
233    CursorPaginatedResponse, CursorPagination, CursorPaginationParams, PaginatedResponse,
234};
235#[cfg(any(feature = "std", feature = "alloc"))]
236pub use pagination::{KeysetPaginatedResponse, KeysetPaginationParams};
237pub use query::SortDirection;
238#[cfg(any(feature = "std", feature = "alloc"))]
239pub use query::{FilterEntry, FilterParams, SearchParams, SortParams};
240#[cfg(any(feature = "std", feature = "alloc"))]
241pub use range::{ByteRange, ContentRange, ParseRangeError, RangeHeader};
242#[cfg(any(feature = "std", feature = "alloc"))]
243pub use ratelimit::RateLimitInfo;
244#[cfg(all(any(feature = "std", feature = "alloc"), feature = "uuid"))]
245pub use request_id::{RequestId, RequestIdError, RequestIdParseError};
246#[cfg(any(feature = "std", feature = "alloc"))]
247pub use response::{ApiResponse, ApiResponseBuilder, ResponseMeta};
248pub use retry::{BackoffStrategy, Idempotent, RetryPolicy};
249#[cfg(any(feature = "std", feature = "alloc"))]
250pub use retry::{RetryAfter, RetryAfterParseError};
251#[cfg(any(feature = "std", feature = "alloc"))]
252pub use slug::{Slug, SlugError};
253pub use status::StatusCode;
254#[cfg(all(any(feature = "std", feature = "alloc"), feature = "uuid"))]
255pub use traceparent::{SamplingFlags, SpanId, TraceContext, TraceContextError, TraceId};
256#[cfg(any(feature = "std", feature = "alloc"))]
257pub use url::{QueryBuilder, UrlBuilder};
258#[cfg(any(feature = "std", feature = "alloc"))]
259pub use vary::Vary;
260pub use version::{ApiVersion, ApiVersionParseError, SemverTriple};
api_bones/lib.rs

api_bones/
lib.rs
