Define a Structure

This document describes how to define structured data models within Biyard Rust projects using the custom api_model macro, streamlining serialization, validation, API interactions, and database integrations.

🛠️ Using the api_model Macro

The api_model macro supports two types of attributes:

• Structure Attributes: Applied to the entire struct, specifying API endpoints, supported actions, database tables, and response behaviors.
• Field Attributes: Applied individually to fields, specifying primary keys, relationships, and serialization rules.

This document specifically explains structure attributes.

📌 Structure Attributes

Structure attributes configure API endpoints, database associations, and model-specific actions:

• api_model automatically attaches derives of Debug, Clone, serde::Deserialize, serde::Serialize, Default, PartialEq by default.
• It also add schemars::JsonSchema and aide::OperationIo for server feature.

Syntax Example:

#![allow(unused)]
fn main() {
#[api_model(base = "/v1/users", table = "users")]
pub struct User {
    #[api_model(primary_key)]
    pub id: i64,
    pub username: String,
}
}

📖 Attribute Definitions

📖 Field Attributes

Field attributes specify behaviors at the individual field level:

⚙️ Practical Struct Example:

Here's a complete, clearly structured Rust model:

#![allow(unused)]
fn main() {
#[api_model(
    base = "/v1/users",
    table = "users",
    queryable = [(sort = Sorter)],
    action = [signup(code = String, param = u64), login(test = Vec<String>)],
    read_action = read_data,
    action_by_id = [get_data, update_data],
    response = [signup(UserResponse)]
)]
#[derive(Debug, Clone, Default)]
pub struct User {
    #[api_model(primary_key)]
    pub id: i64,

    pub username: String,

    #[api_model(nullable)]
    pub email: Option<String>,

    #[api_model(skip)]
    pub password_hash: String,
}
}

This setup ensures:

• Clear alignment of API paths and database table structures.
• Automatic generation of API clients and database CRUD operations.
• Custom request and response handling for specified actions.

✅ Recommended Best Practices

• Clearly define your base attribute to reflect your API structure.
• Always explicitly specify the associated table for clarity and database operations.
• Define custom parameters and response types for actions explicitly when required.

Following these best practices ensures your models are consistent, maintainable, and intuitive within the Biyard Rust ecosystem.

📌 Generated Summary Structure (UserSummary):

The macro identifies fields marked with #[api_model(summary)] and generates a simplified struct called UserSummary:

🚩 Automatically Generated Struct:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct UserSummary {
    pub id: i64,
    pub created_at: i64,
    pub updated_at: i64,
    pub nickname: Option<String>,
}
}

🎯 Purpose of the Summary Struct:

The UserSummary structure is designed to provide concise, efficient, and safe data exchange:

• API List Responses: Clearly optimized for list-based API responses (e.g., listing users without sensitive data).
• Performance: Reduces payload size and overhead by excluding non-summary fields.
• Security: Automatically excludes sensitive fields (e.g., email, password) not explicitly marked for summary.

📖 Rules for Generating Summary Structures:

• Fields must explicitly include the summary attribute to appear in the summary structure.
• The original model struct remains unaffected; the summary struct is an additional, simplified representation.
• Useful for API endpoints designed specifically for listing or simplified views.

✅ Recommended Best Practices:

• Clearly select summary fields carefully to exclude sensitive information.
• Leverage summary structures for efficient API responses.
• Regularly verify and adjust summary fields based on API usage patterns.

Following these best practices ensures safe, performant, and clear API data exchange within your Biyard Rust ecosystem.