Rust api

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

Symptom	Don't Just Say	Ask Instead
Constructor with 8 parameters	"Use a builder"	Which parameters are required vs optional?
Caller ignores return value	"Add must_use"	Is ignoring this value ever correct?
Adding enum variant breaks users	"It's a breaking change"	Should this enum be #[non_exhaustive]?
Method named get_name()	"Remove the get_"	Does this do more than return a field?
as_string() allocates	"Rename to to_string()"	What is the actual cost of this conversion?

---

Quick Decisions

Scenario	Use	Why
Many optional fields in constructor	Builder pattern	Self-documenting, flexible
Required + optional fields	Typestate builder	Compiler enforces required fields
All fields have sensible defaults	#[derive(Default)]	Works with ..Default::default()
Return value must not be ignored	#[must_use]	Compiler warns on silent drop
Builder struct or method chain	#[must_use] on type + methods	Prevents accidental drop
Public enum that may grow	#[non_exhaustive]	Add variants without breaking change
Public struct that may grow	#[non_exhaustive] + constructor	Add fields without breaking change
Adding methods to external types	Extension trait (TypeExt)	Works around orphan rules
Public type minimum traits	Debug, Clone, PartialEq	Basic ecosystem interop
Serde in a library crate	Feature flag, not hard dep	Users who don't need it don't pay
Free reference conversion	as_ prefix	Signals O(1), no allocation
Allocating conversion	to_ prefix	Signals cost
Ownership-consuming conversion	into_ prefix	Signals self is consumed
Simple field accessor	No get_ prefix	name() not get_name()
Boolean-returning method	is_/has_/can_ prefix	Reads naturally in conditions

---

Builder Pattern

Choose the right builder variant based on your requirements:

Decision

Variant	When	build() returns
Infallible	All fields have defaults	T
Fallible	Validation can fail at runtime	Result<T, E>
Typestate	Required fields enforced at compile time	T
Consuming (mut self)	Most common, simple chaining	Depends
Borrowing (&mut self)	Builder reused for multiple instances	Depends

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:

Type Category	Derive
Minimum (all public types)	Debug, Clone, PartialEq
ID / key types	Debug, Clone, Copy, PartialEq, Eq, Hash
Small value types	Debug, Clone, Copy, PartialEq, Default
Config / options	Debug, Clone, PartialEq, Default
Error types	Debug, Clone, PartialEq, Eq
HashMap keys	Add Eq, Hash
BTreeMap keys	Add Eq, Ord, PartialOrd
Serde support	#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]

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

---

Naming Quick Reference

Conversion Prefixes

Prefix	Cost	Ownership	Example
as_	Free O(1)	&self -> &U	as_str(), as_bytes(), as_slice()
to_	Allocates/computes	&self -> U	to_string(), to_vec(), to_lowercase()
into_	Consumes self	self -> U	into_inner(), into_bytes(), into_vec()

Accessor Naming

Pattern	Name	Not
Simple field access	name(), len()	get_name(), get_len()
Fallible lookup	get(), get_mut()	find() (unless searching)
Boolean check	is_empty(), has_key(), can_write()	empty(), key_exists()
Setter	set_name(value)	name(value) (unless builder)

Iterator Methods

Method	Yields	Ownership
iter()	&T	Borrows collection
iter_mut()	&mut T	Mutably borrows
into_iter()	T	Consumes collection

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

General Rules

Element	Convention	Example	Not
Types, traits, enums	UpperCamelCase	HttpServer	HTTPServer
Enum variants	UpperCamelCase	NotFound	NOT_FOUND
Functions, methods	snake_case	parse_json()	parseJSON()
Constants, statics	SCREAMING_SNAKE_CASE	MAX_RETRIES	maxRetries
Lifetimes	Short lowercase	'a, 'de, 'src	'input_lifetime
Type params	Single uppercase	T, E, K, V	ElementType
Acronyms	Treat as words	Uuid, HttpClient	UUID, HTTPClient
Crate names	No -rs/-rust suffix	json-parser	json-parser-rs

---

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

Reference	Read When
api-patterns	Implementing builders, choosing #[must_use]/#[non_exhaustive], extension traits, Default, common traits, serde gating
api-naming	Naming methods, types, conversions, iterators, or crate names
api-documentation	Writing doc comments, examples, error/panic/safety sections, intra-doc links, Cargo.toml metadata

---

Cross-References

Need	Skill
Error types for Result-returning APIs	rust-errors
Newtype patterns, typestate, PhantomData	rust-types
Trait design, generics, dispatch	rust-types
Testing doc examples	rust-quality
Clippy lints for API quality	rust-quality
Ownership decisions in API signatures	rust-ownership