api-design

API Design Skill

Expert guidance for designing robust, type-safe APIs and data structures in Tauri applications.

Overview

This skill provides guidance for:

• Designing Tauri command APIs
• Creating type-safe DTOs (Data Transfer Objects)
• API documentation and contracts
• Request/response patterns
• Error handling in APIs
• API versioning and evolution

When This Skill Applies

This skill activates when:

• Creating new Tauri commands
• Designing request/response DTOs
• Planning API structure
• Documenting API contracts
• Refactoring existing APIs
• Handling API versioning

API Design Principles

1. Type Safety First

✓ Good: Explicit, typed structures

use serde::{Deserialize, Serialize};
use specta::Type;

#[derive(Serialize, Deserialize, Type, Clone)]
#[specta(inline)]
pub struct CreateFormulaDto {
    /// Formula name (2-100 characters)
    #[serde(alias = "formulaName")]
    pub name: String,

    /// Species code (e.g., "pig", "chicken")
    #[serde(alias = "speciesCode")]
    pub species_code: String,

    /// Optional description
    pub description: Option<String>,

    /// Formula materials
    pub materials: Vec<FormulaMaterialDto>,
}

#[derive(Serialize, Deserialize, Type, Clone)]
#[specta(inline)]
pub struct FormulaMaterialDto {
    /// Material code
    #[serde(alias = "materialCode")]
    pub material_code: String,

    /// Proportion in percentage (0-100)
    pub proportion: f64,
}

✗ Bad: Untyped or generic structures

// ✗ Avoid generic maps
pub type RequestData = HashMap<String, serde_json::Value>;

// ✗ Avoid raw JSON
pub fn create_formula(data: serde_json::Value) -> Result<Formula>;

2. Consistent Naming Conventions

Rust → TypeScript Mapping:

Rust	TypeScript	Notes
snake_case	camelCase	Auto-converted by specta
formula_id	formulaId	Use #[serde(alias)] for compatibility
species_code	speciesCode	Keep consistent