API Design

Core Question

What does the caller need, and what should the compiler prevent?

Every API decision flows from this:

• What is the minimum the caller must provide?
• What mistakes can the type system catch at compile time?
• What is the cost of each operation, and does the name communicate it?

If the caller can misuse your API without a compiler error, the API needs work.

API → Design Question

Quick Decisions

Builder Pattern

Choose the right builder variant based on your requirements:

Decision

Infallible Builder

#[derive(Default)]
#[must_use = "builders do nothing unless you call build()"]
pub struct WidgetBuilder {
    color: Option<Color>,
    size: Option<Size>,
}

impl WidgetBuilder {
    pub fn color(mut self, color: Color) -> Self {
        self.color = Some(color);
        self
    }

    pub fn build(self) -> Widget {
        Widget {
            color: self.color.unwrap_or(Color::Black),
            size: self.size.unwrap_or(Size::Medium),
        }
    }
}

Typestate Builder (compile-time required fields)

pub struct NoUrl;
pub struct HasUrl(String);

pub struct ClientBuilder<Url> {
    url: Url,
    timeout: Option<Duration>,
}

impl ClientBuilder<NoUrl> {
    pub fn new() -> Self {
        Self { url: NoUrl, timeout: None }
    }

    pub fn url(self, url: String) -> ClientBuilder<HasUrl> {
        ClientBuilder { url: HasUrl(url), timeout: self.timeout }
    }
}

impl ClientBuilder<HasUrl> {
    pub fn build(self) -> Client {
        Client { url: self.url.0, timeout: self.timeout }
    }
}

Common Traits Checklist

Derive these for every public type unless you have a reason not to:

Implement manually when derive does the wrong thing (e.g., case-insensitive equality, redacting sensitive fields in Debug).

Naming Quick Reference

Conversion Prefixes

Accessor Naming

Iterator Methods

Iterator type names match their method: iter() -> Iter, into_iter() -> IntoIter, keys() -> Keys.

General Rules

Usage Scenarios

Scenario 1: Designing a Library Config Type

You need a Config struct with 3 required fields and 5 optional fields.

1. Use a builder with typestate for the 3 required fields
2. Add #[must_use] to the builder type
3. Derive Debug, Clone, PartialEq, Default on Config
4. Add #[non_exhaustive] if the struct is public and may gain fields
5. Gate serde behind a feature flag
6. Document with # Examples showing builder usage

Scenario 2: Adding Conversion Methods to a Newtype

You have struct Email(String):

impl Email {
    /// Returns the email as a string slice. O(1), no allocation.
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Returns a new lowercase version. Allocates.
    pub fn to_lowercase(&self) -> Email {
        Email(self.0.to_lowercase())
    }

    /// Consumes the Email, returning the inner String.
    pub fn into_string(self) -> String {
        self.0
    }

    pub fn is_valid(&self) -> bool {
        self.0.contains('@')
    }
}

Scenario 3: Extending an External Type

You need hex encoding for byte slices:

pub trait ByteSliceExt {
    fn as_hex(&self) -> String;
}

impl ByteSliceExt for [u8] {
    fn as_hex(&self) -> String {
        self.iter().map(|b| format!("{b:02x}")).collect()
    }
}

Import use my_crate::ByteSliceExt; to use. Name the trait with Ext suffix.

Reference Index

Cross-References