System Design (LLD)Role-Based Interface Design

Role-Based Interface Design

LevelIntermediate

Duration60 mins

TopicRole-Based Interface Design

3 / 4

Minimal Interface Principle

The Art of Interface Minimalism

In design, whether architectural, graphical, or software, there's a timeless principle: perfection is achieved not when there is nothing more to add, but when there is nothing left to take away.

This principle applies powerfully to interface design. The Minimal Interface Principle is a design discipline that asks: What is the smallest interface that fulfills the client's needs? By pursuing minimalism in our interfaces, we create contracts that are easier to implement, understand, mock, and evolve.

Minimal interfaces aren't about being lazy or incomplete—they're about being precisely sufficient. Every method must earn its place; every signature must justify its existence.

What You Will Learn

By the end of this page, you will understand why minimal interfaces are preferable to comprehensive ones, how to identify and eliminate interface bloat, techniques for achieving interface minimalism without sacrificing utility, and the relationship between minimal interfaces and system flexibility.

What Makes an Interface Minimal

A minimal interface contains exactly the methods required to fulfill its purpose—no more, no less. It is:

Necessary: Every method is used by at least one client
Sufficient: Clients can accomplish their tasks without needing more methods
Non-redundant: No method's functionality duplicates another's
Primitive: Methods are building blocks, not conveniences

Let's contrast minimal and non-minimal interfaces:

minimal-vs-comprehensive.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
// NON-MINIMAL: Comprehensive interface with convenience methods
interface ComprehensiveList<T> {
    // Core operations
    get(index: number): T;
    set(index: number, value: T): void;
    size(): number;
    add(value: T): void;
    remove(index: number): T;
    
    // Convenience methods (derived from core operations)
    isEmpty(): boolean;              // Same as: size() === 0
    first(): T;                      // Same as: get(0)
    last(): T;                       // Same as: get(size() - 1)
    contains(value: T): boolean;     // Can be built with iteration
    indexOf(value: T): number;       // Can be built with iteration
    addAll(values: T[]): void;       // Same as: values.forEach(add)
    removeAll(predicate: Pred<T>): void; // Can be built with iteration + remove
    clear(): void;                   // Same as: while(size() > 0) remove(0)
    toArray(): T[];                  // Can be built with iteration
    forEach(fn: (item: T) => void): void; // Can be built with get + size
    map<U>(fn: (item: T) => U): U[]; // Can be built with iteration
    filter(predicate: Pred<T>): T[]; // Can be built with iteration
    find(predicate: Pred<T>): T | undefined; // Can be built with iteration
    some(predicate: Pred<T>): boolean; // Can be built with iteration
    every(predicate: Pred<T>): boolean; // Can be built with iteration
}
// 18 methods! Most are derivable from a smaller core.
 
// MINIMAL: Only primitive operations
interface List<T> {
    get(index: number): T;
    set(index: number, value: T): void;
    size(): number;
    add(value: T): void;
    remove(index: number): T;
}
// 5 methods. All other behaviors can be built from these.
 
// Utility functions provide convenience WITHOUT bloating the interface
function isEmpty<T>(list: List<T>): boolean {
    return list.size() === 0;
}
 
function first<T>(list: List<T>): T {
    return list.get(0);
}
 
function last<T>(list: List<T>): T {
    return list.get(list.size() - 1);
}
 
function contains<T>(list: List<T>, value: T): boolean {
    for (let i = 0; i < list.size(); i++) {
        if (list.get(i) === value) return true;
    }
    return false;
}
 
function forEach<T>(list: List<T>, fn: (item: T) => void): void {
    for (let i = 0; i < list.size(); i++) {
        fn(list.get(i));
    }
}
 
// Extension methods in languages that support them (C#, Kotlin, Swift)
// Or module-level functions in functional-style code
// Or a ListUtils class with static methods

Why the minimal approach is superior:

Aspect	Comprehensive (18 methods)	Minimal (5 methods)
Implementation effort	Much higher	Minimal
Methods to test	18	5
Mocking complexity	High	Low
Cognitive load	High	Low
Odds of bugs	Higher	Lower
Flexibility for implementers	Limited	High

The minimal interface empowers implementers and consumers alike. Implementers need only provide five methods; consumers get the same utility through composable utility functions.

The Primitives Test

Ask yourself: 'Can this method be implemented purely in terms of other methods on this interface?' If yes, it's a convenience method that belongs in a utility class, not in the interface itself. If no, it's a primitive that likely belongs in the interface.

The Costs of Interface Bloat

Every unnecessary method in an interface carries hidden costs. Understanding these costs makes the case for minimalism compelling.

Cost 1: Implementation Burden

Every method in an interface must be implemented by every implementing class. Non-minimal interfaces create a multiplication effect:

implementation-burden.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// Bloated interface
interface MessageQueue {
    send(message: Message): void;
    sendBatch(messages: Message[]): void;    // Can be built from send()
    sendDelayed(message: Message, delay: Duration): void;
    receive(): Message | null;
    receiveBatch(max: number): Message[];    // Can be built from receive()
    peek(): Message | null;
    acknowledge(messageId: string): void;
    reject(messageId: string): void;
    requeueAll(): void;                      // Can be built from other methods
    purge(): void;
    getQueueSize(): number;
    getQueueDepth(): number;                 // Often same as getQueueSize()
    getConsumerCount(): number;
    pause(): void;
    resume(): void;
    // ... 15 methods
}
 
// Implementation burden calculation:
// - In-memory queue for testing: 15 implementations
// - RabbitMQ adapter: 15 implementations
// - SQS adapter: 15 implementations
// - Kafka adapter: 15 implementations
// - Azure Service Bus adapter: 15 implementations
// Total: 75 method implementations
 
// If interface was minimal (7 core methods):
// Total: 35 method implementations
// Savings: 40 fewer methods to write, test, and maintain!

Cost 2: Testing Explosion

Each method requires test coverage for each implementation. The test matrix grows rapidly with interface size.

Testing Burden by Interface Size
Interface Size	Implementations	Test Methods (assuming 3 tests/method)
5 methods (minimal)	5 implementations	75 tests
15 methods (bloated)	5 implementations	225 tests
5 methods (minimal)	10 implementations	150 tests
15 methods (bloated)	10 implementations	450 tests

Cost 3: Inconsistency Risk

When convenience methods are in the interface, each implementation might behave slightly differently. When they're external utilities built on primitives, behavior is guaranteed consistent.

inconsistency-risk.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// PROBLEM: Convenience methods in interface lead to inconsistency
 
interface Collection<T> {
    add(item: T): void;
    remove(item: T): boolean;
    addAll(items: T[]): void;  // Convenience: should be items.forEach(add)
}
 
class ArrayCollection<T> implements Collection<T> {
    addAll(items: T[]): void {
        // Implementation A: Calls add() for each
        items.forEach(item => this.add(item));
    }
}
 
class SetCollection<T> implements Collection<T> {
    addAll(items: T[]): void {
        // Implementation B: Bulk operation (more efficient, different semantics)
        this.items = new Set([...this.items, ...items]);
        // Oops! Didn't trigger add() side effects like logging
    }
}
 
// Now code that relies on add() being called is broken for SetCollection!
// This inconsistency was enabled by including addAll in the interface.
 
// SOLUTION: addAll as external utility ensures consistency
 
interface Collection<T> {
    add(item: T): void;
    remove(item: T): boolean;
}
 
function addAll<T>(collection: Collection<T>, items: T[]): void {
    // ALWAYS calls add() - behavior is consistent across all implementations
    items.forEach(item => collection.add(item));
}

Bloat Compounds Over Time

Once a method is in a public interface, removing it is a breaking change. Interface bloat is easy to add and nearly impossible to remove. This asymmetry means every method added to an interface is effectively a permanent commitment. Choose wisely.

Identifying Interface Minimization Opportunities

How do we identify which methods can be removed from an interface? Here are concrete techniques:

Technique 1: Derivability Analysis

For each method, ask: Can this be implemented using only the other methods? If yes, it's a candidate for removal.

derivability-analysis.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
interface Stack<T> {
    push(item: T): void;
    pop(): T;
    peek(): T;        // Derivable: pop() then push() back
    isEmpty(): boolean; // Derivable if we add size()
    size(): number;
    clear(): void;    // Derivable: while(!isEmpty()) pop()
    toArray(): T[];   // Derivable: pop all, store, push back
}
 
// Derivability Matrix:
// +---------+----------------------------+
// | Method  | Derivable From             |
// +---------+----------------------------+
// | push    | PRIMITIVE (not derivable)  |
// | pop     | PRIMITIVE (not derivable)  |
// | peek    | pop + push                 |
// | isEmpty | size === 0                 |
// | size    | PRIMITIVE (or track count) |
// | clear   | while loop + pop           |
// | toArray | while loop + pop + push    |
// +---------+----------------------------+
 
// Minimal interface:
interface Stack<T> {
    push(item: T): void;
    pop(): T;
    size(): number;
}
 
// 3 methods instead of 7 — same capability!

Technique 2: Orthogonality Check

Methods should be orthogonal—each provides unique capability not covered by others. Overlapping or redundant methods violate minimalism.

orthogonality-check.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// Non-orthogonal interface (redundant methods)
interface UserFinder {
    findById(id: string): User | null;
    findByIdOrThrow(id: string): User;    // Redundant: findById + throw if null
    findByIdOptional(id: string): Optional<User>; // Redundant: same as findById
    existsById(id: string): boolean;       // Redundant: findById !== null
    findByEmail(email: string): User | null;
    findByUsername(username: string): User | null;
    findByEmailOrUsername(input: string): User | null; // Redundant: can call both
}
 
// Orthogonal interface (each method is unique)
interface UserFinder {
    findById(id: string): User | null;
    findByEmail(email: string): User | null;
    findByUsername(username: string): User | null;
}
 
// Convenience wrappers as external functions:
function findByIdOrThrow(finder: UserFinder, id: string): User {
    const user = finder.findById(id);
    if (!user) throw new UserNotFoundError(id);
    return user;
}
 
function existsById(finder: UserFinder, id: string): boolean {
    return finder.findById(id) !== null;
}
 
function findByEmailOrUsername(finder: UserFinder, input: string): User | null {
    return finder.findByEmail(input) ?? finder.findByUsername(input);
}

Technique 3: Usage Frequency Analysis

Methods used by only one client or in rare edge cases are candidates for removal. They can exist as extension methods or utilities rather than polluting every implementation.

The Three-Client Rule

A method should be in an interface only if at least three different clients need it. One client's need is specific; two might be coincidence; three suggests a genuine primitive. Apply this rule to avoid adding methods 'just in case.'

Primitives vs. Conveniences

The key distinction in minimal interface design is between primitives (methods that must be in the interface) and conveniences (methods that can be built from primitives).

Primitives have these characteristics:

Cannot be implemented in terms of other interface methods
Require access to internal state or capabilities
Define the essential operations of the abstraction
Are typically the minimum required for the role

Conveniences have these characteristics:

Can be implemented using only interface methods
Don't require special access to internals
Provide ergonomic shortcuts
Could vary in implementation but shouldn't

Primitives (Keep in Interface)

•read(buffer) — requires stream access
•write(data) — requires output channel
•authenticate(creds) — requires auth subsystem
•execute(query) — requires database access
•get(key) — requires storage access
•put(key, value) — requires storage mutation

Conveniences (Move to Utilities)

•readAll() — loop calling read()
•writeLine(text) — write(text + newline)
•isAuthenticated() — derived from auth state
•existsInDatabase(id) — execute query, check result
•getOrDefault(key, default) — get(key) ?? default
•putIfAbsent(key, value) — if !has(key) put(k,v)

primitives-example.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
// Example: Cache interface
 
// NON-MINIMAL with conveniences mixed in
interface Cache<K, V> {
    // Primitives
    get(key: K): V | undefined;
    set(key: K, value: V, ttl?: Duration): void;
    delete(key: K): boolean;
    has(key: K): boolean;
    
    // Conveniences (derivable)
    getOrSet(key: K, factory: () => V): V;      // get() ?? (set(), get())
    getOrDefault(key: K, defaultValue: V): V;   // get() ?? defaultValue
    setIfAbsent(key: K, value: V): boolean;     // !has() && set()
    deleteAll(keys: K[]): number;               // keys.map(delete).filter(Boolean).length
    clear(): void;                              // delete all keys (needs iteration primitive)
}
 
// MINIMAL interface
interface Cache<K, V> {
    get(key: K): V | undefined;
    set(key: K, value: V, ttl?: Duration): void;
    delete(key: K): boolean;
    keys(): Iterable<K>;  // Primitive needed for iteration-based conveniences
}
 
// has() is borderline: could be primitive or get(key) !== undefined
// Decision: Leave as primitive if performance matters (O(1) vs O(n) in some caches)
 
// Convenience functions as module utilities
namespace CacheUtils {
    export function has<K, V>(cache: Cache<K, V>, key: K): boolean {
        return cache.get(key) !== undefined;
    }
    
    export function getOrDefault<K, V>(cache: Cache<K, V>, key: K, defaultValue: V): V {
        return cache.get(key) ?? defaultValue;
    }
    
    export function getOrSet<K, V>(cache: Cache<K, V>, key: K, factory: () => V): V {
        let value = cache.get(key);
        if (value === undefined) {
            value = factory();
            cache.set(key, value);
        }
        return value;
    }
    
    export function setIfAbsent<K, V>(cache: Cache<K, V>, key: K, value: V): boolean {
        if (!has(cache, key)) {
            cache.set(key, value);
            return true;
        }
        return false;
    }
    
    export function deleteAll<K, V>(cache: Cache<K, V>, keys: K[]): number {
        return keys.filter(key => cache.delete(key)).length;
    }
    
    export function clear<K, V>(cache: Cache<K, V>): void {
        for (const key of cache.keys()) {
            cache.delete(key);
        }
    }
}

The Performance Exception

Sometimes a 'derivable' method should remain a primitive for performance reasons. If clear() on a cache can be O(1) internally but O(n) when built from delete(), it may be worth keeping. Document these exceptions explicitly.

The Role of Extension Methods and Utilities

When we remove convenience methods from interfaces, where do they go? The answer depends on your language and style, but the concept is consistent: conveniences become external functions that operate on the minimal interface.

Approach 1: Extension Methods (C#, Kotlin, Swift)

Languages with extension methods let you add functionality to interfaces without modifying them:

extension-methods.cs
C#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
// Minimal interface
public interface IStack<T>
{
    void Push(T item);
    T Pop();
    int Size { get; }
}
 
// Extension methods add conveniences without bloating the interface
public static class StackExtensions
{
    public static bool IsEmpty<T>(this IStack<T> stack)
        => stack.Size == 0;
    
    public static T Peek<T>(this IStack<T> stack)
    {
        var item = stack.Pop();
        stack.Push(item);
        return item;
    }
    
    public static void Clear<T>(this IStack<T> stack)
    {
        while (!stack.IsEmpty())
            stack.Pop();
    }
    
    public static T[] ToArray<T>(this IStack<T> stack)
    {
        var items = new List<T>();
        while (!stack.IsEmpty())
            items.Add(stack.Pop());
        items.Reverse();
        foreach (var item in items)
            stack.Push(item);
        return items.ToArray();
    }
}
 
// Usage feels like the methods are on the interface
IStack<int> stack = new ArrayStack<int>();
stack.Push(1);
stack.Push(2);
bool empty = stack.IsEmpty();  // Extension method
int top = stack.Peek();        // Extension method

Approach 2: Module Functions (TypeScript, JavaScript, Go)

In languages without extension methods, module-level functions serve the same purpose:

module-functions.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
// stack.ts - defines the minimal interface and primitives
export interface Stack<T> {
    push(item: T): void;
    pop(): T;
    size(): number;
}
 
// stack-utils.ts - convenience functions
import type { Stack } from './stack';
 
export function isEmpty<T>(stack: Stack<T>): boolean {
    return stack.size() === 0;
}
 
export function peek<T>(stack: Stack<T>): T {
    const item = stack.pop();
    stack.push(item);
    return item;
}
 
export function clear<T>(stack: Stack<T>): void {
    while (!isEmpty(stack)) {
        stack.pop();
    }
}
 
// With function overloading for ergonomics
export function pushAll<T>(stack: Stack<T>, items: T[]): void {
    items.forEach(item => stack.push(item));
}
 
// Usage
import { Stack } from './stack';
import { isEmpty, peek, clear } from './stack-utils';
 
const stack: Stack<number> = createStack();
stack.push(1);
stack.push(2);
if (!isEmpty(stack)) {
    console.log(peek(stack));
}
clear(stack);

Approach 3: Wrapper/Decorator Classes

For complex conveniences that need state, a wrapper class can provide enhanced functionality:

wrapper-approach.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// Minimal interface
interface Cache<K, V> {
    get(key: K): V | undefined;
    set(key: K, value: V): void;
    delete(key: K): boolean;
}
 
// Enhanced wrapper with additional features
class EnhancedCache<K, V> {
    constructor(private readonly cache: Cache<K, V>) {}
    
    // Delegate primitives
    get(key: K): V | undefined { return this.cache.get(key); }
    set(key: K, value: V): void { this.cache.set(key, value); }
    delete(key: K): boolean { return this.cache.delete(key); }
    
    // Add conveniences
    getOrSet(key: K, factory: () => V): V {
        let value = this.cache.get(key);
        if (value === undefined) {
            value = factory();
            this.cache.set(key, value);
        }
        return value;
    }
    
    // Add features that need state
    private metrics = { hits: 0, misses: 0 };
    
    getWithMetrics(key: K): V | undefined {
        const value = this.cache.get(key);
        if (value !== undefined) this.metrics.hits++;
        else this.metrics.misses++;
        return value;
    }
    
    getHitRate(): number {
        const total = this.metrics.hits + this.metrics.misses;
        return total === 0 ? 0 : this.metrics.hits / total;
    }
}
 
// Usage: wrap any minimal Cache implementation
const simpleCache: Cache<string, number> = new InMemoryCache();
const enhancedCache = new EnhancedCache(simpleCache);
enhancedCache.getOrSet('key', () => computeExpensiveValue());

Separation of Concerns

By separating primitives (in the interface) from conveniences (in utilities), we get the best of both worlds: minimal implementation burden for interface providers, and rich functionality for consumers. The interface is lean; the ecosystem is rich.

Minimal Interfaces Enable Maximum Flexibility

A counterintuitive truth: smaller interfaces provide more flexibility, not less. This is because minimal interfaces have a larger solution space—more implementations can satisfy their constraints.

Consider this principle through the lens of the Liskov Substitution Principle: the fewer requirements an interface imposes, the more types can satisfy it, and the more places it can be used.

flexibility-demonstration.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// LARGE INTERFACE: Few implementations possible
interface ComprehensiveStorage {
    get(key: string): string | null;
    set(key: string, value: string): void;
    delete(key: string): void;
    list(): string[];
    search(pattern: string): string[];
    setWithExpiry(key: string, value: string, ttl: number): void;
    getRemaining(key: string): number;
    atomic<T>(operation: () => T): T;
    watch(key: string, callback: (value: string) => void): void;
    unwatch(key: string): void;
}
 
// Very few systems can implement ALL of these:
// - In-memory Map: Can't do atomic(), watch()  
// - localStorage: Can't do search(), atomic(), watch(), setWithExpiry()  
// - Simple file-based: Can't do atomic(), watch()  
// - S3: Can't do atomic(), watch(), setWithExpiry()  
 
// MINIMAL INTERFACE: Many implementations possible
interface Storage {
    get(key: string): string | null;
    set(key: string, value: string): void;
    delete(key: string): void;
}
 
// Almost ANYTHING can implement this:
// ✓ In-memory Map
// ✓ localStorage
// ✓ sessionStorage
// ✓ File-based storage
// ✓ Redis
// ✓ DynamoDB
// ✓ S3
// ✓ IndexedDB
// ✓ Simple HTTP key-value API
// ✓ Mock for testing
// ✓ Null/no-op for disabled features
// ✓ Composite/fallback storage
// ✓ Encrypted storage wrapper
// ✓ Compressed storage wrapper
// ✓ Logged storage wrapper
 
// The minimal interface is implementable by 15+ things;
// the comprehensive interface by maybe 1-2.

The Composition Advantage

With minimal interfaces, advanced features emerge through composition rather than being forced into the core interface:

composition-advantage.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
// Minimal interface
interface Storage {
    get(key: string): string | null;
    set(key: string, value: string): void;
    delete(key: string): void;
}
 
// Additional capability interfaces (also minimal)
interface Expirable {
    setWithExpiry(key: string, value: string, ttl: number): void;
}
 
interface Watchable {
    watch(key: string, callback: (value: string) => void): Unsubscribe;
}
 
interface Listable {
    list(): string[];
}
 
// Implementations declare what they support
class RedisStorage implements Storage, Expirable, Watchable, Listable {
    // Implements all four interfaces
}
 
class InMemoryStorage implements Storage, Listable {
    // Only implements Storage and Listable
}
 
class LocalStorage implements Storage {
    // Only implements minimal Storage
}
 
// Client code composes what it needs
function cacheWithFallback(
    cache: Storage & Expirable,  // Needs expiry
    fallback: Storage            // Just needs basic storage
): Storage {
    return {
        get(key) {
            return cache.get(key) ?? fallback.get(key);
        },
        set(key, value) {
            cache.setWithExpiry(key, value, 3600);
            fallback.set(key, value);
        },
        delete(key) {
            cache.delete(key);
            fallback.delete(key);
        }
    };
}
 
// This works because the minimal Storage interface has many implementers
const cached = cacheWithFallback(
    new RedisStorage(),     // Has Storage + Expirable
    new LocalStorage()      // Has only Storage
);

Minimum Viable Interface

Design interfaces like products: start with the Minimum Viable Interface (MVI). Add methods only when there's clear demand from multiple clients. It's far easier to add a method to an interface than to remove one.

Practical Guidelines for Interface Minimalism

Here are actionable guidelines for designing minimal interfaces:

1. Start with Client Needs, Not Provider Capabilities

Design the interface from the perspective of the simplest client that would use it. What's the minimum they need?

Minimalism Checklist

•Is every method called by at least 3 clients? If not, consider making it a utility.
•Can any method be derived from others? If yes, move it to utilities.
•Is the interface easy to mock completely? If mocking is tedious, it's too fat.
•Can you name the interface with a specific role noun? If you need 'And' in the name (like ReaderAndWriter), split it.
•Would the simplest implementation be short? If a trivial implementation would be over 50 lines, reconsider.
•Would you want to implement this interface from scratch? If it feels daunting, it's too big.

2. Apply the 'Regret Test'

Before adding a method, ask: 'Will I regret having this method in 2 years?' Methods added for 'convenience' or 'just in case' often become legacy burdens.

3. Use the 'New Implementation Test'

Imagine a new team is implementing your interface. Would they find every method natural and necessary? Or would they groan at having to implement methods they know the real clients don't use?

4. Separate Read from Write

When in doubt, split read operations from write operations. Clients that only read shouldn't depend on write methods, and vice versa.

read-write-split.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// Instead of one interface with all operations
interface UserRepository {
    findById(id: string): User | null;
    findByEmail(email: string): User | null;
    save(user: User): void;
    delete(userId: string): void;
}
 
// Consider splitting by capability
interface UserQuerier {
    findById(id: string): User | null;
    findByEmail(email: string): User | null;
}
 
interface UserPersister {
    save(user: User): void;
    delete(userId: string): void;
}
 
// Clients that only query don't depend on save/delete
// Clients that only persist don't depend on query methods
class UserReportingService {
    constructor(private users: UserQuerier) {
        // Can't accidentally call save() or delete()
    }
}
 
class UserCleanupJob {
    constructor(private users: UserPersister) {
        // Focused on deletion, can't accidentally query
    }
}

CQRS Influence

This read/write split aligns with Command Query Responsibility Segregation (CQRS) principles. Even if you're not implementing full CQRS, the interface-level separation brings clarity and reduces coupling.

Summary: The Discipline of Less

The Minimal Interface Principle is a discipline that transforms how we approach interface design. By removing every method that doesn't absolutely need to be there, we create interfaces that are easier to implement, test, understand, and extend.

Key Takeaways

•Minimal interfaces contain only primitive operations — Methods that cannot be derived from others and require access to internals.
•Convenience methods belong in utilities — Extension methods, module functions, or wrapper classes provide conveniences without bloating the interface.
•Interface bloat has compounding costs — Implementation burden, testing explosion, inconsistency risk, and permanent API commitment.
•Use derivability analysis — If a method can be implemented using other interface methods, it's a candidate for removal.
•Smaller interfaces enable more implementations — The minimum solution space is the maximum flexibility.
•Apply the regret test and new implementation test — Would you regret this method? Would a new implementer find it necessary?
•Consider read/write splits — Separating query and command interfaces often reveals natural minimal interfaces.

What's next:

We've seen how to think in roles, design for specific clients, and minimize interface size. The final piece is role discovery—how to identify the right roles and interfaces from scratch when designing a new system. This is where the principles come together into a practical methodology.

Page Complete

You now understand the Minimal Interface Principle—the discipline of designing the smallest interfaces that still serve their purpose. Remember: perfection is not when there's nothing left to add, but when there's nothing left to take away. Next, we'll learn the process of discovering roles and interfaces from domain analysis.

3 / 4

Loading learning content...

System Design (LLD)Role-Based Interface Design

Role-Based Interface Design

LevelIntermediate

Duration60 mins

TopicRole-Based Interface Design

3 / 4

Minimal Interface Principle

The Art of Interface Minimalism

In design, whether architectural, graphical, or software, there's a timeless principle: perfection is achieved not when there is nothing more to add, but when there is nothing left to take away.

Minimal interfaces aren't about being lazy or incomplete—they're about being precisely sufficient. Every method must earn its place; every signature must justify its existence.

What You Will Learn

What Makes an Interface Minimal

A minimal interface contains exactly the methods required to fulfill its purpose—no more, no less. It is:

Necessary: Every method is used by at least one client
Sufficient: Clients can accomplish their tasks without needing more methods
Non-redundant: No method's functionality duplicates another's
Primitive: Methods are building blocks, not conveniences

Let's contrast minimal and non-minimal interfaces:

minimal-vs-comprehensive.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
// NON-MINIMAL: Comprehensive interface with convenience methods
interface ComprehensiveList<T> {
    // Core operations
    get(index: number): T;
    set(index: number, value: T): void;
    size(): number;
    add(value: T): void;
    remove(index: number): T;
    
    // Convenience methods (derived from core operations)
    isEmpty(): boolean;              // Same as: size() === 0
    first(): T;                      // Same as: get(0)
    last(): T;                       // Same as: get(size() - 1)
    contains(value: T): boolean;     // Can be built with iteration
    indexOf(value: T): number;       // Can be built with iteration
    addAll(values: T[]): void;       // Same as: values.forEach(add)
    removeAll(predicate: Pred<T>): void; // Can be built with iteration + remove
    clear(): void;                   // Same as: while(size() > 0) remove(0)
    toArray(): T[];                  // Can be built with iteration
    forEach(fn: (item: T) => void): void; // Can be built with get + size
    map<U>(fn: (item: T) => U): U[]; // Can be built with iteration
    filter(predicate: Pred<T>): T[]; // Can be built with iteration
    find(predicate: Pred<T>): T | undefined; // Can be built with iteration
    some(predicate: Pred<T>): boolean; // Can be built with iteration
    every(predicate: Pred<T>): boolean; // Can be built with iteration
}
// 18 methods! Most are derivable from a smaller core.
 
// MINIMAL: Only primitive operations
interface List<T> {
    get(index: number): T;
    set(index: number, value: T): void;
    size(): number;
    add(value: T): void;
    remove(index: number): T;
}
// 5 methods. All other behaviors can be built from these.
 
// Utility functions provide convenience WITHOUT bloating the interface
function isEmpty<T>(list: List<T>): boolean {
    return list.size() === 0;
}
 
function first<T>(list: List<T>): T {
    return list.get(0);
}
 
function last<T>(list: List<T>): T {
    return list.get(list.size() - 1);
}
 
function contains<T>(list: List<T>, value: T): boolean {
    for (let i = 0; i < list.size(); i++) {
        if (list.get(i) === value) return true;
    }
    return false;
}
 
function forEach<T>(list: List<T>, fn: (item: T) => void): void {
    for (let i = 0; i < list.size(); i++) {
        fn(list.get(i));
    }
}
 
// Extension methods in languages that support them (C#, Kotlin, Swift)
// Or module-level functions in functional-style code
// Or a ListUtils class with static methods

Why the minimal approach is superior:

Aspect	Comprehensive (18 methods)	Minimal (5 methods)
Implementation effort	Much higher	Minimal
Methods to test	18	5
Mocking complexity	High	Low
Cognitive load	High	Low
Odds of bugs	Higher	Lower
Flexibility for implementers	Limited	High

The minimal interface empowers implementers and consumers alike. Implementers need only provide five methods; consumers get the same utility through composable utility functions.

The Primitives Test

The Costs of Interface Bloat

Every unnecessary method in an interface carries hidden costs. Understanding these costs makes the case for minimalism compelling.

Cost 1: Implementation Burden

Every method in an interface must be implemented by every implementing class. Non-minimal interfaces create a multiplication effect:

implementation-burden.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// Bloated interface
interface MessageQueue {
    send(message: Message): void;
    sendBatch(messages: Message[]): void;    // Can be built from send()
    sendDelayed(message: Message, delay: Duration): void;
    receive(): Message | null;
    receiveBatch(max: number): Message[];    // Can be built from receive()
    peek(): Message | null;
    acknowledge(messageId: string): void;
    reject(messageId: string): void;
    requeueAll(): void;                      // Can be built from other methods
    purge(): void;
    getQueueSize(): number;
    getQueueDepth(): number;                 // Often same as getQueueSize()
    getConsumerCount(): number;
    pause(): void;
    resume(): void;
    // ... 15 methods
}
 
// Implementation burden calculation:
// - In-memory queue for testing: 15 implementations
// - RabbitMQ adapter: 15 implementations
// - SQS adapter: 15 implementations
// - Kafka adapter: 15 implementations
// - Azure Service Bus adapter: 15 implementations
// Total: 75 method implementations
 
// If interface was minimal (7 core methods):
// Total: 35 method implementations
// Savings: 40 fewer methods to write, test, and maintain!

Cost 2: Testing Explosion

Each method requires test coverage for each implementation. The test matrix grows rapidly with interface size.

Testing Burden by Interface Size
Interface Size	Implementations	Test Methods (assuming 3 tests/method)
5 methods (minimal)	5 implementations	75 tests
15 methods (bloated)	5 implementations	225 tests
5 methods (minimal)	10 implementations	150 tests
15 methods (bloated)	10 implementations	450 tests

Cost 3: Inconsistency Risk

When convenience methods are in the interface, each implementation might behave slightly differently. When they're external utilities built on primitives, behavior is guaranteed consistent.

inconsistency-risk.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// PROBLEM: Convenience methods in interface lead to inconsistency
 
interface Collection<T> {
    add(item: T): void;
    remove(item: T): boolean;
    addAll(items: T[]): void;  // Convenience: should be items.forEach(add)
}
 
class ArrayCollection<T> implements Collection<T> {
    addAll(items: T[]): void {
        // Implementation A: Calls add() for each
        items.forEach(item => this.add(item));
    }
}
 
class SetCollection<T> implements Collection<T> {
    addAll(items: T[]): void {
        // Implementation B: Bulk operation (more efficient, different semantics)
        this.items = new Set([...this.items, ...items]);
        // Oops! Didn't trigger add() side effects like logging
    }
}
 
// Now code that relies on add() being called is broken for SetCollection!
// This inconsistency was enabled by including addAll in the interface.
 
// SOLUTION: addAll as external utility ensures consistency
 
interface Collection<T> {
    add(item: T): void;
    remove(item: T): boolean;
}
 
function addAll<T>(collection: Collection<T>, items: T[]): void {
    // ALWAYS calls add() - behavior is consistent across all implementations
    items.forEach(item => collection.add(item));
}

Bloat Compounds Over Time

Identifying Interface Minimization Opportunities

How do we identify which methods can be removed from an interface? Here are concrete techniques:

Technique 1: Derivability Analysis

For each method, ask: Can this be implemented using only the other methods? If yes, it's a candidate for removal.

derivability-analysis.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
interface Stack<T> {
    push(item: T): void;
    pop(): T;
    peek(): T;        // Derivable: pop() then push() back
    isEmpty(): boolean; // Derivable if we add size()
    size(): number;
    clear(): void;    // Derivable: while(!isEmpty()) pop()
    toArray(): T[];   // Derivable: pop all, store, push back
}
 
// Derivability Matrix:
// +---------+----------------------------+
// | Method  | Derivable From             |
// +---------+----------------------------+
// | push    | PRIMITIVE (not derivable)  |
// | pop     | PRIMITIVE (not derivable)  |
// | peek    | pop + push                 |
// | isEmpty | size === 0                 |
// | size    | PRIMITIVE (or track count) |
// | clear   | while loop + pop           |
// | toArray | while loop + pop + push    |
// +---------+----------------------------+
 
// Minimal interface:
interface Stack<T> {
    push(item: T): void;
    pop(): T;
    size(): number;
}
 
// 3 methods instead of 7 — same capability!

Technique 2: Orthogonality Check

Methods should be orthogonal—each provides unique capability not covered by others. Overlapping or redundant methods violate minimalism.

orthogonality-check.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// Non-orthogonal interface (redundant methods)
interface UserFinder {
    findById(id: string): User | null;
    findByIdOrThrow(id: string): User;    // Redundant: findById + throw if null
    findByIdOptional(id: string): Optional<User>; // Redundant: same as findById
    existsById(id: string): boolean;       // Redundant: findById !== null
    findByEmail(email: string): User | null;
    findByUsername(username: string): User | null;
    findByEmailOrUsername(input: string): User | null; // Redundant: can call both
}
 
// Orthogonal interface (each method is unique)
interface UserFinder {
    findById(id: string): User | null;
    findByEmail(email: string): User | null;
    findByUsername(username: string): User | null;
}
 
// Convenience wrappers as external functions:
function findByIdOrThrow(finder: UserFinder, id: string): User {
    const user = finder.findById(id);
    if (!user) throw new UserNotFoundError(id);
    return user;
}
 
function existsById(finder: UserFinder, id: string): boolean {
    return finder.findById(id) !== null;
}
 
function findByEmailOrUsername(finder: UserFinder, input: string): User | null {
    return finder.findByEmail(input) ?? finder.findByUsername(input);
}

Technique 3: Usage Frequency Analysis

Methods used by only one client or in rare edge cases are candidates for removal. They can exist as extension methods or utilities rather than polluting every implementation.

The Three-Client Rule

Primitives vs. Conveniences

The key distinction in minimal interface design is between primitives (methods that must be in the interface) and conveniences (methods that can be built from primitives).

Primitives have these characteristics:

Cannot be implemented in terms of other interface methods
Require access to internal state or capabilities
Define the essential operations of the abstraction
Are typically the minimum required for the role

Conveniences have these characteristics:

Can be implemented using only interface methods
Don't require special access to internals
Provide ergonomic shortcuts
Could vary in implementation but shouldn't

Primitives (Keep in Interface)

•read(buffer) — requires stream access
•write(data) — requires output channel
•authenticate(creds) — requires auth subsystem
•execute(query) — requires database access
•get(key) — requires storage access
•put(key, value) — requires storage mutation

Conveniences (Move to Utilities)

•readAll() — loop calling read()
•writeLine(text) — write(text + newline)
•isAuthenticated() — derived from auth state
•existsInDatabase(id) — execute query, check result
•getOrDefault(key, default) — get(key) ?? default
•putIfAbsent(key, value) — if !has(key) put(k,v)

primitives-example.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
// Example: Cache interface
 
// NON-MINIMAL with conveniences mixed in
interface Cache<K, V> {
    // Primitives
    get(key: K): V | undefined;
    set(key: K, value: V, ttl?: Duration): void;
    delete(key: K): boolean;
    has(key: K): boolean;
    
    // Conveniences (derivable)
    getOrSet(key: K, factory: () => V): V;      // get() ?? (set(), get())
    getOrDefault(key: K, defaultValue: V): V;   // get() ?? defaultValue
    setIfAbsent(key: K, value: V): boolean;     // !has() && set()
    deleteAll(keys: K[]): number;               // keys.map(delete).filter(Boolean).length
    clear(): void;                              // delete all keys (needs iteration primitive)
}
 
// MINIMAL interface
interface Cache<K, V> {
    get(key: K): V | undefined;
    set(key: K, value: V, ttl?: Duration): void;
    delete(key: K): boolean;
    keys(): Iterable<K>;  // Primitive needed for iteration-based conveniences
}
 
// has() is borderline: could be primitive or get(key) !== undefined
// Decision: Leave as primitive if performance matters (O(1) vs O(n) in some caches)
 
// Convenience functions as module utilities
namespace CacheUtils {
    export function has<K, V>(cache: Cache<K, V>, key: K): boolean {
        return cache.get(key) !== undefined;
    }
    
    export function getOrDefault<K, V>(cache: Cache<K, V>, key: K, defaultValue: V): V {
        return cache.get(key) ?? defaultValue;
    }
    
    export function getOrSet<K, V>(cache: Cache<K, V>, key: K, factory: () => V): V {
        let value = cache.get(key);
        if (value === undefined) {
            value = factory();
            cache.set(key, value);
        }
        return value;
    }
    
    export function setIfAbsent<K, V>(cache: Cache<K, V>, key: K, value: V): boolean {
        if (!has(cache, key)) {
            cache.set(key, value);
            return true;
        }
        return false;
    }
    
    export function deleteAll<K, V>(cache: Cache<K, V>, keys: K[]): number {
        return keys.filter(key => cache.delete(key)).length;
    }
    
    export function clear<K, V>(cache: Cache<K, V>): void {
        for (const key of cache.keys()) {
            cache.delete(key);
        }
    }
}

The Performance Exception

The Role of Extension Methods and Utilities

Approach 1: Extension Methods (C#, Kotlin, Swift)

Languages with extension methods let you add functionality to interfaces without modifying them:

extension-methods.cs
C#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
// Minimal interface
public interface IStack<T>
{
    void Push(T item);
    T Pop();
    int Size { get; }
}
 
// Extension methods add conveniences without bloating the interface
public static class StackExtensions
{
    public static bool IsEmpty<T>(this IStack<T> stack)
        => stack.Size == 0;
    
    public static T Peek<T>(this IStack<T> stack)
    {
        var item = stack.Pop();
        stack.Push(item);
        return item;
    }
    
    public static void Clear<T>(this IStack<T> stack)
    {
        while (!stack.IsEmpty())
            stack.Pop();
    }
    
    public static T[] ToArray<T>(this IStack<T> stack)
    {
        var items = new List<T>();
        while (!stack.IsEmpty())
            items.Add(stack.Pop());
        items.Reverse();
        foreach (var item in items)
            stack.Push(item);
        return items.ToArray();
    }
}
 
// Usage feels like the methods are on the interface
IStack<int> stack = new ArrayStack<int>();
stack.Push(1);
stack.Push(2);
bool empty = stack.IsEmpty();  // Extension method
int top = stack.Peek();        // Extension method

Approach 2: Module Functions (TypeScript, JavaScript, Go)

In languages without extension methods, module-level functions serve the same purpose:

module-functions.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
// stack.ts - defines the minimal interface and primitives
export interface Stack<T> {
    push(item: T): void;
    pop(): T;
    size(): number;
}
 
// stack-utils.ts - convenience functions
import type { Stack } from './stack';
 
export function isEmpty<T>(stack: Stack<T>): boolean {
    return stack.size() === 0;
}
 
export function peek<T>(stack: Stack<T>): T {
    const item = stack.pop();
    stack.push(item);
    return item;
}
 
export function clear<T>(stack: Stack<T>): void {
    while (!isEmpty(stack)) {
        stack.pop();
    }
}
 
// With function overloading for ergonomics
export function pushAll<T>(stack: Stack<T>, items: T[]): void {
    items.forEach(item => stack.push(item));
}
 
// Usage
import { Stack } from './stack';
import { isEmpty, peek, clear } from './stack-utils';
 
const stack: Stack<number> = createStack();
stack.push(1);
stack.push(2);
if (!isEmpty(stack)) {
    console.log(peek(stack));
}
clear(stack);

Approach 3: Wrapper/Decorator Classes

For complex conveniences that need state, a wrapper class can provide enhanced functionality:

wrapper-approach.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// Minimal interface
interface Cache<K, V> {
    get(key: K): V | undefined;
    set(key: K, value: V): void;
    delete(key: K): boolean;
}
 
// Enhanced wrapper with additional features
class EnhancedCache<K, V> {
    constructor(private readonly cache: Cache<K, V>) {}
    
    // Delegate primitives
    get(key: K): V | undefined { return this.cache.get(key); }
    set(key: K, value: V): void { this.cache.set(key, value); }
    delete(key: K): boolean { return this.cache.delete(key); }
    
    // Add conveniences
    getOrSet(key: K, factory: () => V): V {
        let value = this.cache.get(key);
        if (value === undefined) {
            value = factory();
            this.cache.set(key, value);
        }
        return value;
    }
    
    // Add features that need state
    private metrics = { hits: 0, misses: 0 };
    
    getWithMetrics(key: K): V | undefined {
        const value = this.cache.get(key);
        if (value !== undefined) this.metrics.hits++;
        else this.metrics.misses++;
        return value;
    }
    
    getHitRate(): number {
        const total = this.metrics.hits + this.metrics.misses;
        return total === 0 ? 0 : this.metrics.hits / total;
    }
}
 
// Usage: wrap any minimal Cache implementation
const simpleCache: Cache<string, number> = new InMemoryCache();
const enhancedCache = new EnhancedCache(simpleCache);
enhancedCache.getOrSet('key', () => computeExpensiveValue());

Separation of Concerns

Minimal Interfaces Enable Maximum Flexibility

Consider this principle through the lens of the Liskov Substitution Principle: the fewer requirements an interface imposes, the more types can satisfy it, and the more places it can be used.

flexibility-demonstration.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// LARGE INTERFACE: Few implementations possible
interface ComprehensiveStorage {
    get(key: string): string | null;
    set(key: string, value: string): void;
    delete(key: string): void;
    list(): string[];
    search(pattern: string): string[];
    setWithExpiry(key: string, value: string, ttl: number): void;
    getRemaining(key: string): number;
    atomic<T>(operation: () => T): T;
    watch(key: string, callback: (value: string) => void): void;
    unwatch(key: string): void;
}
 
// Very few systems can implement ALL of these:
// - In-memory Map: Can't do atomic(), watch()  
// - localStorage: Can't do search(), atomic(), watch(), setWithExpiry()  
// - Simple file-based: Can't do atomic(), watch()  
// - S3: Can't do atomic(), watch(), setWithExpiry()  
 
// MINIMAL INTERFACE: Many implementations possible
interface Storage {
    get(key: string): string | null;
    set(key: string, value: string): void;
    delete(key: string): void;
}
 
// Almost ANYTHING can implement this:
// ✓ In-memory Map
// ✓ localStorage
// ✓ sessionStorage
// ✓ File-based storage
// ✓ Redis
// ✓ DynamoDB
// ✓ S3
// ✓ IndexedDB
// ✓ Simple HTTP key-value API
// ✓ Mock for testing
// ✓ Null/no-op for disabled features
// ✓ Composite/fallback storage
// ✓ Encrypted storage wrapper
// ✓ Compressed storage wrapper
// ✓ Logged storage wrapper
 
// The minimal interface is implementable by 15+ things;
// the comprehensive interface by maybe 1-2.

The Composition Advantage

With minimal interfaces, advanced features emerge through composition rather than being forced into the core interface:

composition-advantage.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
// Minimal interface
interface Storage {
    get(key: string): string | null;
    set(key: string, value: string): void;
    delete(key: string): void;
}
 
// Additional capability interfaces (also minimal)
interface Expirable {
    setWithExpiry(key: string, value: string, ttl: number): void;
}
 
interface Watchable {
    watch(key: string, callback: (value: string) => void): Unsubscribe;
}
 
interface Listable {
    list(): string[];
}
 
// Implementations declare what they support
class RedisStorage implements Storage, Expirable, Watchable, Listable {
    // Implements all four interfaces
}
 
class InMemoryStorage implements Storage, Listable {
    // Only implements Storage and Listable
}
 
class LocalStorage implements Storage {
    // Only implements minimal Storage
}
 
// Client code composes what it needs
function cacheWithFallback(
    cache: Storage & Expirable,  // Needs expiry
    fallback: Storage            // Just needs basic storage
): Storage {
    return {
        get(key) {
            return cache.get(key) ?? fallback.get(key);
        },
        set(key, value) {
            cache.setWithExpiry(key, value, 3600);
            fallback.set(key, value);
        },
        delete(key) {
            cache.delete(key);
            fallback.delete(key);
        }
    };
}
 
// This works because the minimal Storage interface has many implementers
const cached = cacheWithFallback(
    new RedisStorage(),     // Has Storage + Expirable
    new LocalStorage()      // Has only Storage
);

Minimum Viable Interface

Practical Guidelines for Interface Minimalism

Here are actionable guidelines for designing minimal interfaces:

1. Start with Client Needs, Not Provider Capabilities

Design the interface from the perspective of the simplest client that would use it. What's the minimum they need?

Minimalism Checklist

•Is every method called by at least 3 clients? If not, consider making it a utility.
•Can any method be derived from others? If yes, move it to utilities.
•Is the interface easy to mock completely? If mocking is tedious, it's too fat.
•Can you name the interface with a specific role noun? If you need 'And' in the name (like ReaderAndWriter), split it.
•Would the simplest implementation be short? If a trivial implementation would be over 50 lines, reconsider.
•Would you want to implement this interface from scratch? If it feels daunting, it's too big.

2. Apply the 'Regret Test'

Before adding a method, ask: 'Will I regret having this method in 2 years?' Methods added for 'convenience' or 'just in case' often become legacy burdens.

3. Use the 'New Implementation Test'

Imagine a new team is implementing your interface. Would they find every method natural and necessary? Or would they groan at having to implement methods they know the real clients don't use?

4. Separate Read from Write

When in doubt, split read operations from write operations. Clients that only read shouldn't depend on write methods, and vice versa.

read-write-split.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// Instead of one interface with all operations
interface UserRepository {
    findById(id: string): User | null;
    findByEmail(email: string): User | null;
    save(user: User): void;
    delete(userId: string): void;
}
 
// Consider splitting by capability
interface UserQuerier {
    findById(id: string): User | null;
    findByEmail(email: string): User | null;
}
 
interface UserPersister {
    save(user: User): void;
    delete(userId: string): void;
}
 
// Clients that only query don't depend on save/delete
// Clients that only persist don't depend on query methods
class UserReportingService {
    constructor(private users: UserQuerier) {
        // Can't accidentally call save() or delete()
    }
}
 
class UserCleanupJob {
    constructor(private users: UserPersister) {
        // Focused on deletion, can't accidentally query
    }
}

CQRS Influence

Summary: The Discipline of Less

Key Takeaways

•Minimal interfaces contain only primitive operations — Methods that cannot be derived from others and require access to internals.
•Convenience methods belong in utilities — Extension methods, module functions, or wrapper classes provide conveniences without bloating the interface.
•Interface bloat has compounding costs — Implementation burden, testing explosion, inconsistency risk, and permanent API commitment.
•Use derivability analysis — If a method can be implemented using other interface methods, it's a candidate for removal.
•Smaller interfaces enable more implementations — The minimum solution space is the maximum flexibility.
•Apply the regret test and new implementation test — Would you regret this method? Would a new implementer find it necessary?
•Consider read/write splits — Separating query and command interfaces often reveals natural minimal interfaces.

What's next:

Page Complete

3 / 4