Struct ApiResponse 

pub struct ApiResponse<T: Serialize> {
    pub api_version: &'static str,
    pub timestamp: u64,
    pub request_id: Option<String>,
    pub command: Option<String>,
    pub success: bool,
    pub data: Option<T>,
    pub error: Option<ApiError>,
}

Unified API response envelope.

All CLI commands and daemon endpoints should return this structure for consistent agent parsing.

Example

use rch_common::api::{ApiResponse, ApiError};
use rch_common::ErrorCode;

// Success response
#[derive(serde::Serialize)]
struct WorkerList {
    workers: Vec<String>,
    count: usize,
}

let data = WorkerList {
    workers: vec!["worker-1".to_string(), "worker-2".to_string()],
    count: 2,
};
let response = ApiResponse::ok("workers list", data);

// Error response
let error = ApiError::from_code(ErrorCode::ConfigNotFound);
let response: ApiResponse<()> = ApiResponse::err("config show", error);

Fields

api_version: &'static str

API version for compatibility detection.

timestamp: u64

Unix timestamp when response was generated.

request_id: Option<String>

Optional request ID for correlation/tracing.

command: Option<String>

Command that produced this response (e.g., “workers list”).

success: bool

Whether the operation succeeded.

data: Option<T>

Response data on success.

error: Option<ApiError>

Error details on failure.

Implementations

impl<T: Serialize> ApiResponse<T>

pub fn ok(command: impl Into<String>, data: T) -> Self

Create a successful response.

Arguments

• command - Command name that produced this response
• data - Response payload

pub fn ok_data(data: T) -> Self

Create a successful response without command name.

Useful for daemon endpoints where command context isn’t applicable.

pub fn with_request_id(self, id: impl Into<String>) -> Self

Add a request ID for correlation.

pub fn with_command(self, command: impl Into<String>) -> Self

Add or override command name.

impl<T: Serialize> ApiResponse<T>

pub fn err(command: impl Into<String>, error: ApiError) -> Self

Create an error response.

Arguments

• command - Command name that failed
• error - Error details

pub fn err_only(error: ApiError) -> Self

Create an error response without command name.

Useful for daemon endpoints.

impl ApiResponse<()>

pub fn ok_empty(command: impl Into<String>) -> Self

Create a simple success response with no data.

Trait Implementations

impl<T: Clone + Serialize> Clone for ApiResponse<T>

fn clone(&self) -> ApiResponse<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + Serialize> Debug for ApiResponse<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Deserialize<'static> for ApiResponse<T>

where T: Deserialize<'static> + Serialize,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'static>,

Deserialize this value from the given Serde deserializer.

impl<T: Serialize, E: Into<ApiError>> From<Result<T, E>> for ApiResponse<T>

fn from(result: Result<T, E>) -> Self

Converts to this type from the input type.

impl<T: Serialize + JsonSchema> JsonSchema for ApiResponse<T>

fn schema_name() -> String

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn is_referenceable() -> bool

Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.

impl<T> Serialize for ApiResponse<T>

where T: Serialize + Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.