The contract before the code
You spend three days writing a Rust library. The logic works. The tests pass. You publish it to crates.io. Two weeks later, a user opens an issue. They are trying to pass a Vec<String> where your API expects a &[str]. Another user complains that your error type returns a raw string, so they cannot match on specific failure cases. A third user accidentally mutates your internal state because you exposed a field that should have stayed private. The code works, but the interface fights the person using it.
API design in Rust is not about web endpoints or HTTP routes. It is about the contract between your crate and the code that calls it. Every function signature, every visibility modifier, and every error type forms a boundary. Cross that boundary poorly, and you create a maintenance nightmare. Treat your public interface like a well-labeled toolbox. The user should grab exactly what they need without seeing the springs and gears inside. If they can accidentally trigger a spring, the design failed.
Define your terms early. A struct groups data. An impl block attaches behavior. Result<T, E> communicates success or failure without panicking. Visibility keywords like pub and pub(crate) control who sees what. Combine these pieces deliberately, and the compiler becomes your enforcement officer rather than your adversary.
Boundaries and visibility
Rust modules create namespaces. Files and mod declarations carve your crate into logical sections. The pub keyword is the only bridge between those sections. When you mark something pub, you are making a promise to every developer who ever depends on your crate. That promise carries weight. Change a public field name, and you break downstream code. Change a public method signature, and you force a major version bump.
Keep the public surface small. Expose only what callers actually need. Hide implementation details behind private fields and pub(crate) helpers. This separation gives you the freedom to refactor internals without touching the contract. If you later swap a Vec for a BTreeMap to improve lookup performance, the public API stays identical. The caller never notices.
Minimal example
Start with a type that holds user information and validates it at creation time. The goal is to prevent invalid states from ever existing.
/// Represents a validated user account.
/// Fields are private to enforce validation through `new`.
pub struct User {
username: String,
email: String,
}
/// Errors that can occur during user creation.
/// Deriving Debug and PartialEq enables logging and testing.
#[derive(Debug, PartialEq)]
pub enum UserError {
EmptyUsername,
InvalidEmail,
}
impl User {
/// Creates a new `User` after validating the inputs.
/// Returns an error variant if validation fails.
pub fn new(username: String, email: String) -> Result<Self, UserError> {
// Reject empty usernames to maintain a consistent identity
if username.is_empty() {
return Err(UserError::EmptyUsername);
}
// Basic email validation to prevent malformed addresses
if !email.contains('@') {
return Err(UserError::InvalidEmail);
}
// Return the constructed instance wrapped in Ok
Ok(User { username, email })
}
}
The pub keyword on the struct makes it accessible outside the module. The fields themselves are private by default. That is intentional. You control how the struct gets constructed. The new function lives in an impl block, which is the standard place for constructors and methods. Returning Result<Self, UserError> forces the caller to handle both success and failure paths. The compiler will not let them ignore the error.
Treat the constructor as a gatekeeper. If it returns Ok, the invariant holds forever.
How the compiler enforces your design
Watch how the compiler enforces this boundary. If a caller tries to construct the struct directly, they hit a wall.
// This will not compile because fields are private.
// let user = User { username: "alice".into(), email: "alice@example.com".into() };
The compiler rejects this with a "private field" error. You must go through User::new. That single rule gives you the power to enforce invariants. You can validate, allocate, or transform data before the struct ever reaches the caller.
Notice the error type. We use an enum instead of a String. Returning a string for errors is a common trap. Strings are opaque. Callers cannot match on them. They cannot compare them for equality. An enum gives the caller a closed set of possibilities. They can write match result { Ok(u) => ..., Err(UserError::EmptyUsername) => ... }. The compiler guarantees they handle every variant.
Convention aside: Rust developers prefer #[derive(Debug)] on every public type. It costs nothing and saves hours of debugging when someone prints your type in a panic message. Add Clone only when you actually need to duplicate the data. Deriving it blindly encourages unnecessary heap allocations.
A realistic library interface
Real libraries rarely stop at one constructor. They need methods that transform state, query data, or integrate with other types. Here is a slightly more complete interface for a configuration loader.
/// Configuration for a network service.
/// Implements Clone to allow safe sharing across threads.
#[derive(Debug, Clone)]
pub struct Config {
host: String,
port: u16,
timeout_secs: u64,
}
/// Errors specific to configuration parsing.
#[derive(Debug)]
pub enum ConfigError {
MissingField(String),
InvalidPort(u16),
}
impl Config {
/// Parses configuration from a key-value map.
/// Takes a reference to avoid taking ownership of the caller's data.
pub fn from_map(map: &std::collections::HashMap<String, String>) -> Result<Self, ConfigError> {
// Extract host or return a specific missing field error
let host = map.get("host")
.ok_or_else(|| ConfigError::MissingField("host".into()))?;
// Parse port and map any parse failure to a custom error
let port: u16 = map.get("port")
.ok_or_else(|| ConfigError::MissingField("port".into()))?
.parse()
.map_err(|_| ConfigError::InvalidPort(0))?;
// Port zero is reserved and invalid for standard TCP/UDP
if port == 0 {
return Err(ConfigError::InvalidPort(0));
}
// Provide a sensible default if timeout is omitted
let timeout = map.get("timeout")
.unwrap_or(&"30".into())
.parse::<u64>()
.unwrap_or(30);
Ok(Config {
host: host.clone(),
port,
timeout_secs: timeout,
})
}
/// Returns the full connection address.
/// Takes &self because it only reads internal state.
pub fn address(&self) -> String {
format!("{}:{}", self.host, self.port)
}
}
The from_map function takes a reference to a HashMap. Taking &HashMap instead of HashMap avoids an unnecessary allocation. The caller keeps ownership of their data. The ? operator propagates errors cleanly. If a field is missing, the function returns early with a specific error variant. The address method takes &self, which is the standard signature for read-only queries. It returns a String because it constructs new data. The caller owns the result.
Convention aside: Rust developers prefer from_map or try_from over new when the constructor takes a specific external format. Reserve new for simple, direct construction. This naming pattern signals intent before the caller even reads the documentation.
Design your methods to return owned data or references, never both interchangeably. Pick one and stick to it.
Common traps and compiler signals
API design trips up when you ignore the compiler's hints or fight Rust's type system. Here are the most common traps.
Returning String for errors breaks pattern matching. The compiler will not stop you, but your users will suffer. Switch to an enum.
Exposing internal fields invites misuse. If you mark a field pub, you promise that field will exist and keep its type forever. Change it later, and you break every crate that depends on yours. Keep fields private. Provide getters or methods instead.
Ignoring trait bounds creates confusing error messages. If your function requires a type that implements Display, say so in the signature.
pub fn print_info(item: &impl std::fmt::Display) {
println!("{}", item);
}
If you skip the bound and try to format an unsupported type, the compiler throws E0277 (trait bound not satisfied). The error points to the missing trait, but a clear signature prevents the mistake entirely.
Overcomplicating generics hides the actual purpose of the function. Start with concrete types. Add generics only when you measure a real need or when the abstraction saves significant duplication. The compiler will optimize monomorphized code just as well as hand-written generics, but readability drops fast.
Forgetting #[must_use] on functions that return Result or Option is another silent failure. Without the attribute, a caller can ignore the return value and the compiler stays quiet. Add the attribute to force awareness.
#[must_use]
pub fn validate(&self) -> Result<(), ValidationError> {
// validation logic
}
The compiler will warn if the result is discarded. Treat warnings as errors in your CI pipeline. A clean build means no ignored outcomes.
Mismatched types in public signatures cause E0308 errors for your users. If your function returns &str but the caller expects String, the compiler stops them. Fix the signature to return what the caller actually needs, or document the lifetime clearly. Do not force the caller to clone data they do not need.
Guard your public surface like a vault. Every exposed function is a promise you must keep for years.
Choosing your interface patterns
You will face choices when shaping an interface. Pick the right tool for the job.
Use Result<T, E> when the operation can fail and the caller needs to know why. Use Option<T> when absence is a normal, non-error state. Use a custom error enum when you have multiple distinct failure modes that callers might handle differently. Use String or &str for errors only when you are wrapping third-party failures that you cannot categorize.
Use pub on types and functions that form the external contract. Use pub(crate) on helpers that other modules in your crate need but external users should never touch. Use pub(super) when a child module needs to expose something to its parent without leaking it further.
Use a new constructor when the type requires simple validation or transformation. Use a from or try_from method when converting from another specific type. Use a builder pattern when the struct has many optional fields or complex validation rules that make a single constructor unwieldy.
Use &self for methods that read state. Use &mut self for methods that modify state in place. Use self by value when the method consumes the instance and returns something else, like a parser that turns a buffer into tokens.
Match the signature to the data flow. Let the type system do the heavy lifting.
Where to go next
API design is a skill that compounds. Every crate you publish teaches you what callers actually need versus what you think they need. Read the documentation of libraries you use daily. Notice how they hide complexity behind clean signatures. Apply those patterns to your own code.