restful 0.2.0

REST API helpers: validated Axum extractors, response envelopes, pagination, ordering, and field selection
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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

use super::error_type::HttpErrorResponseType;

/// Structured error details for failed API operations.
///
/// ```
/// use restful::response::HttpErrorResponse;
///
/// let err = HttpErrorResponse::not_found("Item not found");
/// let json = serde_json::to_value(&err).unwrap();
/// assert_eq!(json["type"], "NotFound");
/// assert_eq!(json["message"], "Item not found");
/// ```
#[derive(Debug, serde::Serialize)]
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
pub struct HttpErrorResponse {
    /// Machine-readable error category.
    #[serde(rename = "type")]
    pub error_type: HttpErrorResponseType,
    /// Human-readable error description.
    pub message: String,
    /// Optional structured error details (e.g., field-level validation errors).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub details: Option<serde_json::Value>,
}

impl HttpErrorResponse {
    pub fn bad_request(message: impl Into<String>) -> Self {
        Self {
            error_type: HttpErrorResponseType::BadRequest,
            message: message.into(),
            details: None,
        }
    }

    pub fn unauthorized(message: impl Into<String>) -> Self {
        Self {
            error_type: HttpErrorResponseType::Unauthorized,
            message: message.into(),
            details: None,
        }
    }

    pub fn forbidden(message: impl Into<String>) -> Self {
        Self {
            error_type: HttpErrorResponseType::Forbidden,
            message: message.into(),
            details: None,
        }
    }

    pub fn step_up_required(message: impl Into<String>) -> Self {
        Self {
            error_type: HttpErrorResponseType::StepUpRequired,
            message: message.into(),
            details: None,
        }
    }

    pub fn method_not_allowed(message: impl Into<String>) -> Self {
        Self {
            error_type: HttpErrorResponseType::MethodNotAllowed,
            message: message.into(),
            details: None,
        }
    }

    pub fn payload_too_large(message: impl Into<String>) -> Self {
        Self {
            error_type: HttpErrorResponseType::PayloadTooLarge,
            message: message.into(),
            details: None,
        }
    }

    pub fn service_unavailable(message: impl Into<String>) -> Self {
        Self {
            error_type: HttpErrorResponseType::ServiceUnavailable,
            message: message.into(),
            details: None,
        }
    }

    pub fn not_found(message: impl Into<String>) -> Self {
        Self {
            error_type: HttpErrorResponseType::NotFound,
            message: message.into(),
            details: None,
        }
    }

    pub fn conflict(message: impl Into<String>) -> Self {
        Self {
            error_type: HttpErrorResponseType::Conflict,
            message: message.into(),
            details: None,
        }
    }

    pub fn unsupported_media_type(message: impl Into<String>) -> Self {
        Self {
            error_type: HttpErrorResponseType::UnsupportedMediaType,
            message: message.into(),
            details: None,
        }
    }

    pub fn validation_error(
        message: impl Into<String>,
        details: Option<serde_json::Value>,
    ) -> Self {
        Self {
            error_type: HttpErrorResponseType::ValidationError,
            message: message.into(),
            details,
        }
    }

    pub fn rate_limited(message: impl Into<String>) -> Self {
        Self {
            error_type: HttpErrorResponseType::RateLimited,
            message: message.into(),
            details: None,
        }
    }

    pub fn internal_server_error(message: impl Into<String>) -> Self {
        Self {
            error_type: HttpErrorResponseType::InternalServerError,
            message: message.into(),
            details: None,
        }
    }
}