api-bones 4.0.1

Opinionated REST API types: errors (RFC 9457), pagination, health checks, and more
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

//! Common RFC-conformant primitive types used across all external APIs.
//!
//! ## Standards
//! - Timestamps: [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) (Internet Date/Time Format)
//! - Identifiers: [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122) (UUID)

#[cfg(all(not(feature = "std"), feature = "alloc", not(feature = "chrono")))]
use alloc::string::String;

/// RFC 3339 timestamp alias for API responses.
///
/// Serializes as `"2026-03-09T15:00:00Z"` via `chrono`'s serde integration.
/// See [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
///
/// # Examples
///
/// ```rust
/// use api_bones::common::Timestamp;
/// let ts: Timestamp = "2026-01-01T00:00:00Z".parse().unwrap();
/// assert_eq!(ts.to_rfc3339(), "2026-01-01T00:00:00+00:00");
/// ```
#[cfg(feature = "chrono")]
pub type Timestamp = chrono::DateTime<chrono::Utc>;

/// RFC 3339 timestamp alias (string fallback when `chrono` feature is disabled).
///
/// Requires `std` or `alloc` when `chrono` is disabled.
#[cfg(all(not(feature = "chrono"), any(feature = "std", feature = "alloc")))]
pub type Timestamp = String;

/// RFC 4122 UUID v4 resource identifier.
///
/// See [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122).
///
/// # Examples
///
/// ```rust
/// use api_bones::common::ResourceId;
/// let id: ResourceId = uuid::Uuid::nil();
/// assert_eq!(id.to_string(), "00000000-0000-0000-0000-000000000000");
/// ```
#[cfg(feature = "uuid")]
pub type ResourceId = uuid::Uuid;

/// Parse an RFC 3339 timestamp string.
///
/// See [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
///
/// # Errors
///
/// Returns a `chrono::ParseError` if `s` is not a valid RFC 3339 timestamp.
///
/// # Examples
///
/// ```rust
/// use api_bones::common::parse_timestamp;
/// let ts = parse_timestamp("2026-03-09T15:00:00Z").unwrap();
/// assert_eq!(ts.to_rfc3339(), "2026-03-09T15:00:00+00:00");
/// ```
#[cfg(feature = "chrono")]
pub fn parse_timestamp(s: &str) -> Result<Timestamp, chrono::ParseError> {
    s.parse()
}

/// Generate a new RFC 4122 v4 resource identifier.
///
/// See [RFC 4122 ยง4.4](https://www.rfc-editor.org/rfc/rfc4122#section-4.4).
///
/// # Examples
///
/// ```rust
/// use api_bones::common::new_resource_id;
/// let id = new_resource_id();
/// assert_eq!(id.get_version_num(), 4);
/// ```
#[cfg(feature = "uuid")]
#[must_use]
pub fn new_resource_id() -> ResourceId {
    uuid::Uuid::new_v4()
}

#[cfg(all(test, any(feature = "uuid", feature = "chrono")))]
mod tests {
    use super::*;

    #[cfg(feature = "uuid")]
    #[test]
    fn resource_id_is_v4() {
        let id = new_resource_id();
        assert_eq!(id.get_version_num(), 4);
    }

    #[cfg(feature = "chrono")]
    #[test]
    fn timestamp_parses_rfc3339() {
        // RFC 3339 format: YYYY-MM-DDTHH:MM:SSZ
        let ts = parse_timestamp("2026-03-09T15:00:00Z").unwrap();
        assert_eq!(ts.to_rfc3339(), "2026-03-09T15:00:00+00:00");
    }
}