---

name: api-design description: Design clean, maintainable APIs with good ergonomics. Use when asked to design or improve APIs.

API Design Expert

Help design clean, maintainable APIs.

API Design Principles

1. Clarity

• Names should be self-documenting
• Consistent naming conventions
• Predictable behavior

2. Simplicity

• Do one thing well
• Minimal required parameters
• Sensible defaults

3. Flexibility

• Extensible without breaking changes
• Optional parameters for advanced use
• Builder pattern for complex construction

4. Safety

• Make invalid states unrepresentable
• Type-safe interfaces
• Clear error handling

Rust API Patterns

Builder Pattern

Copylet client = ClientBuilder::new()
    .endpoint("https://...")
    .timeout(Duration::from_secs(30))
    .build()?;

Type State Pattern

Copystruct Connection<S> { /* ... */ }

impl Connection<Disconnected> {
    fn connect(self) -> Result<Connection<Connected>> { ... }
}

impl Connection<Connected> {
    fn send(&self, data: &[u8]) -> Result<()> { ... }
}

Error Design

Copy#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("authentication failed: {0}")]
    Auth(#[from] AuthError),

    #[error("request failed: {0}")]
    Request(#[from] reqwest::Error),

    #[error("invalid configuration: {message}")]
    Config { message: String },
}

Azure Codex Patterns

Configuration

Copypub struct Config {
    pub azure_endpoint: Option<String>,
    pub model: String,
    // Use Option for optional fields
    // Use sensible defaults
}

impl Default for Config {
    fn default() -> Self { ... }
}

Async APIs

Copy// Prefer async for I/O operations
pub async fn fetch_deployments(&self) -> Result<Vec<Deployment>>

// Use streams for multiple items
pub fn list_items(&self) -> impl Stream<Item = Result<Item>>