api-design

🎨 RUST API DESIGN BEST PRACTICES

TL;DR: Comprehensive API design guidelines for creating ergonomic, maintainable, and idiomatic Rust libraries and services.

🔍 API DESIGN STRATEGY

graph TD
    Start["API Design"] --> Purpose{"API<br>Purpose?"}

    Purpose -->|Library| LibAPI["Library API"]
    Purpose -->|Service| ServiceAPI["Service API"]
    Purpose -->|CLI| CLIAPI["CLI API"]

    LibAPI --> Ergonomics["Ergonomic Design"]
    ServiceAPI --> RESTDesign["REST/gRPC Design"]
    CLIAPI --> CLIDesign["Command Interface"]

    Ergonomics --> FlexibleInputs["Flexible Input Types"]
    Ergonomics --> BuilderPattern["Builder Pattern"]
    Ergonomics --> ErrorDesign["Error Design"]

    RESTDesign --> OpenAPI["OpenAPI Documentation"]
    RESTDesign --> Validation["Input Validation"]
    RESTDesign --> Authentication["Authentication"]

    CLIDesign --> Subcommands["Subcommand Structure"]
    CLIDesign --> Configuration["Configuration Management"]
    CLIDesign --> HelpSystem["Help System"]

    FlexibleInputs --> TraitDesign["Trait Design"]
    BuilderPattern --> TraitDesign
    ErrorDesign --> TraitDesign

    OpenAPI --> AsyncAPI["Async API Patterns"]
    Validation --> AsyncAPI
    Authentication --> AsyncAPI

    Subcommands --> Testing["Testing Strategy"]
    Configuration --> Testing
    HelpSystem --> Testing

    TraitDesign --> Documentation["Documentation"]
    AsyncAPI --> Documentation
    Testing --> Documentation

    Documentation --> APIComplete["API Complete"]

    style Start fill:#4da6ff,stroke:#0066cc,color:white
    style Ergonomics fill:#4dbb5f,stroke:#36873f,color:white
    style RESTDesign fill:#ffa64d,stroke:#cc7a30,color:white
    style CLIDesign fill:#d94dbb,stroke:#a3378a,color:white

🎯 API DESIGN PRINCIPLES

Ergonomic Function Signatures

use std::path::Path;

// ✅ Accept flexible input types
pub fn read_config<P: AsRef<Path>>(path: P) -> Result<Config, ConfigError> {
    let path = path.as_ref();
    // Implementation
}

// ✅ Use Into for string-like parameters
pub fn create_user<S: Into<String>>(name: S, email: S) -> Result<User, UserError> {
    let name = name.into();
    let email = email.into();
    // Implementation
}

// ✅ Prefer borrowing over ownership when possible
pub fn validate_email(email: &str) -> Result<(), ValidationError> {
    // Implementation - doesn't need to own the string
}

// ✅ Return owned data when caller needs ownership
pub fn generate_token() -> String {
    // Implementation returns owned String
}

// ❌ Avoid overly generic signatures without clear benefit
// pub fn process<T, U, F>(input: T, func: F) -> U where F: Fn(T) -> U