System Design (LLD)Designing for Abstraction

Designing for Abstraction

LevelIntermediate

Duration60 mins

TopicDesigning for Abstraction

3 / 4

Stable Interfaces, Flexible Implementations

The Stability-Flexibility Paradox

Software faces a fundamental tension: we need stability for clients to depend on something reliable, yet we need flexibility to evolve as requirements change. How can one exist without sacrificing the other?

The answer lies in a principle that appears paradoxical until understood: stable interfaces enable flexible implementations. By carefully designing interfaces that capture essential operations without exposing incidental implementation details, we create a contract that can remain unchanged even as everything behind it is replaced.

This is the architectural pattern behind every successful long-lived system. The POSIX file system interface has remained stable for decades while implementations evolved from magnetic tapes to SSDs to cloud storage. The SQL language interface works with databases that barely existed when it was designed. APIs built in 2010 still work in 2024 while their implementations have been rewritten multiple times.

This page teaches you to design interfaces with this durability—interfaces that will survive the evolution of your implementations.

What You Will Learn

By the end of this page, you will understand how to design interfaces that remain stable over time, techniques for allowing implementation flexibility without breaking clients, and patterns that enable evolution without modification.

The Interface-Implementation Contract

At the heart of stable interfaces is a clear contract that defines what clients can rely on and what they cannot. This contract becomes the stable artifact that clients depend on—not the implementation.

The Three Layers of a Contract:

Contract Layers
Layer	Description	Stability Requirement
Syntactic	Method signatures, types, parameters	Must never break (compilation errors)
Semantic	What methods do, their meaning	Must never change meaning (logic errors)
Pragmatic	Performance characteristics, resource usage	Should be documented if guaranteed

Syntactic Stability is the baseline—clients' code must continue to compile. But it's insufficient alone. Changing what a method does while keeping its signature breaks clients just as surely as changing the signature.

Semantic Stability is the deeper contract. If save(user) today creates a new user and tomorrow silently updates an existing one, you've broken the semantic contract even though the syntax is unchanged.

Pragmatic Stability is often implicit. If clients rely on findById being O(1), changing it to O(n) breaks their performance assumptions. Document pragmatic guarantees when they matter.

contract-layers.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
/**
 * UserRepository - Persistent storage for User entities.
 * 
 * SYNTACTIC CONTRACT: (enforced by compiler)
 *   The method signatures below define the syntactic contract.
 * 
 * SEMANTIC CONTRACT: (enforced by documentation and tests)
 *   - findById returns the user with the exact id requested, or null
 *   - save is idempotent: saving the same user twice has no side effects
 *   - delete removes the user permanently; future findById returns null
 *   - All operations are atomic: they fully succeed or fully fail
 * 
 * PRAGMATIC CONTRACT: (performance characteristics)
 *   - findById: O(1) average case, may require network roundtrip
 *   - save: O(1) amortized, writes are durable after return
 *   - list: O(n) where n is result size, paginated
 */
interface UserRepository {
    /**
     * Retrieves a user by their unique identifier.
     * 
     * @param id - The user's unique identifier
     * @returns The user if found, null if no user exists with this id
     * @throws InvalidIdError if id format is invalid
     */
    findById(id: UserId): Promise<User | null>;
    
    /**
     * Persists a user to storage.
     * 
     * IDEMPOTENCY: Calling save(user) multiple times with the same user
     * has the same effect as calling it once.
     * 
     * @param user - The user to save (new or existing)
     * @throws ValidationError if user data is invalid
     */
    save(user: User): Promise<void>;
    
    /**
     * Permanently removes a user from storage.
     * 
     * @param id - The identifier of the user to delete
     * @returns true if user was deleted, false if user didn't exist
     */
    delete(id: UserId): Promise<boolean>;
    
    /**
     * Lists users with pagination support.
     * 
     * @param options - Pagination options (limit, offset)
     * @returns Array of users, may be empty
     */
    list(options?: { limit?: number; offset?: number }): Promise<User[]>;
}
 
// The contract is explicit and comprehensive.
// Implementations can vary wildly while honoring this contract:
 
class PostgresUserRepository implements UserRepository { /* ... */ }
class MongoUserRepository implements UserRepository { /* ... */ }
class InMemoryUserRepository implements UserRepository { /* ... */ }
class CachedUserRepository implements UserRepository { /* ... */ }

Document the Semantics

The most stable interfaces have explicit documentation of all three contract layers. If you only define syntax, you haven't defined a contract—you've defined a wish that any implementation might fulfill differently.

Designing for Stability

Creating stable interfaces isn't about predicting the future—it's about understanding what's fundamental and what's accidental in your domain. Interfaces should capture the essential operations while remaining agnostic to how those operations are fulfilled.

Principles for Stable Interface Design

•Focus on Capabilities, Not Mechanisms — Define what clients can do, not how it's done. 'send a message' vs 'add message to queue and poll for delivery confirmation'.
•Use Domain Language — Interfaces using domain terms (Order, Customer, Invoice) are more stable than those using technical terms (Record, Row, Blob).
•Avoid Leaking Implementation Concepts — If changing the implementation would require interface changes, you've leaked. Don't mention SQL, JSON, or specific technologies.
•Prefer Composition Over Features — Small, composable interfaces are more stable than large, feature-rich ones. You can combine simple interfaces; you can't split complex ones.
•Design for the Invariant — Identify what must always be true, regardless of implementation. Design the interface to enforce these invariants.

Case Study: Payment Processing

Consider designing a payment interface. What's essential, and what's implementation detail?

Implementation-Leaking Design

•chargeStripeCard(token: string)
•set3DSecureEnabled(enabled: boolean)
•setWebhookUrl(url: string)
•getStripeCustomerId(): string
•Exposes Stripe-specific concepts
•Can't switch providers without changes

Stable Domain-Focused Design

•charge(amount: Money, method: PaymentMethod)
•refund(paymentId: PaymentId, amount?: Money)
•getPayment(id: PaymentId): Payment
•listPayments(filter: PaymentFilter)
•Uses domain concepts only
•Works with any provider

The domain-focused interface captures what payment processing is at a fundamental level: charging money, refunding it, and querying payment records. This interface can accommodate Stripe, Square, PayPal, or any future provider without changing.

The Stability Test:

Ask: "If I completely rewrote the implementation using different technology, could I keep this interface?" If yes, your interface is stable. If no, you've leaked implementation details.

Extension Points and Flexibility

A stable interface doesn't mean a frozen interface. Well-designed interfaces include extension points—deliberate mechanisms for adding capabilities without breaking existing clients. The key is designing these points intentionally rather than letting them emerge chaotically.

Optional parameters allow adding capabilities without breaking existing calls.

// Version 1.0
interface OrderService {
    createOrder(items: OrderItem[]): Promise<Order>;
}

// Version 1.1 - backward compatible!
interface OrderService {
    createOrder(
        items: OrderItem[], 
        options?: {
            priority?: 'standard' | 'express';  // New!
            giftWrap?: boolean;                 // New!
        }
    ): Promise<Order>;
}

// All existing callers still work:
await service.createOrder(items);

// New callers can use new features:
await service.createOrder(items, { priority: 'express' });

Best Practices:

Place all optional parameters in an options object (easier to extend)
Provide sensible defaults for all options
Document default behavior explicitly
Never require new options for existing use cases

Versioning Strategies

Even the best-designed interface eventually needs to change. Versioning strategies manage this evolution while maintaining backward compatibility for existing clients.

The Compatibility Spectrum:

Types of Changes and Their Impact
Change Type	Example	Impact	Version Bump
Additive	New optional parameter	None—existing code works	Minor (1.0 → 1.1)
Behavioral	Performance improvement	None if contract unchanged	Patch (1.0.0 → 1.0.1)
Deprecation	Mark method as deprecated	Warning only	Minor (1.1 → 1.2)
Breaking	Remove method, change signature	Compilation failure	Major (1.x → 2.0)

Strategies for Non-Breaking Evolution:

1. Additive-Only Changes

The safest evolution: only add, never modify or remove.

// Version 1.0
interface Cache {
    get(key: string): Promise<string | null>;
    set(key: string, value: string): Promise<void>;
}

// Version 1.1 - additive only
interface Cache {
    get(key: string): Promise<string | null>;
    set(key: string, value: string): Promise<void>;
    // NEW: optional TTL parameter
    setWithTTL?(key: string, value: string, ttlSeconds: number): Promise<void>;
    // NEW: batch operations
    getMany?(keys: string[]): Promise<Map<string, string>>;
}

2. Deprecation with Sunset Period

interface UserService {
    /**
     * @deprecated since 1.2.0 - Use findByIdentifier instead.
     * Will be removed in 2.0.0.
     */
    findByEmail(email: string): Promise<User | null>;
    
    // New preferred method
    findByIdentifier(identifier: UserIdentifier): Promise<User | null>;
}

3. Parallel Interfaces

// Original interface remains unchanged
interface PaymentProcessor {
    charge(amount: number, cardToken: string): Promise<ChargeResult>;
}

// New interface exists alongside, not replacing
interface PaymentProcessorV2 {
    charge(request: ChargeRequest): Promise<ChargeResult>;
    // Richer input, same contract
}

// Adapter allows gradual migration
class PaymentProcessorAdapter implements PaymentProcessor {
    constructor(private v2: PaymentProcessorV2) {}
    
    async charge(amount: number, cardToken: string): Promise<ChargeResult> {
        return this.v2.charge({ 
            amount: Money.fromCents(amount), 
            paymentMethod: PaymentMethod.fromToken(cardToken)
        });
    }
}

Breaking Changes Are Expensive

Every breaking change forces all clients to update simultaneously. In a microservices architecture or public API, this can be catastrophic. Reserve breaking changes for major versions, provide long sunset periods, and offer migration tools when possible.

The Open-Closed Principle Connection

The design pattern of stable interfaces with flexible implementations is a direct application of the Open-Closed Principle (OCP): "Software entities should be open for extension but closed for modification."

When you design a stable interface with implementation flexibility:

The interface is closed for modification (it doesn't change)
The system is open for extension (new implementations can be added)

This isn't coincidence—it's the essence of well-designed abstractions.

open-closed-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
67
// The interface is CLOSED - it won't change
interface NotificationChannel {
    send(recipient: Recipient, message: Message): Promise<SendResult>;
    supportsRecipientType(type: RecipientType): boolean;
}
 
// The system is OPEN - unlimited implementations can be added
 
class EmailNotification implements NotificationChannel {
    async send(recipient: Recipient, message: Message): Promise<SendResult> {
        // Email-specific implementation
        return this.emailService.send(recipient.email, message.toHTML());
    }
    
    supportsRecipientType(type: RecipientType): boolean {
        return type === RecipientType.EMAIL;
    }
}
 
class SMSNotification implements NotificationChannel {
    async send(recipient: Recipient, message: Message): Promise<SendResult> {
        // SMS-specific implementation
        return this.smsGateway.send(recipient.phone, message.toPlainText());
    }
    
    supportsRecipientType(type: RecipientType): boolean {
        return type === RecipientType.PHONE;
    }
}
 
class PushNotification implements NotificationChannel {
    async send(recipient: Recipient, message: Message): Promise<SendResult> {
        // Push notification implementation
        return this.pushService.send(recipient.deviceToken, message.toNotification());
    }
    
    supportsRecipientType(type: RecipientType): boolean {
        return type === RecipientType.DEVICE;
    }
}
 
// Adding Slack, Teams, WhatsApp, etc. requires ZERO changes to existing code.
// The interface is stable; implementations are flexible.
 
class NotificationService {
    constructor(private channels: NotificationChannel[]) {}
    
    async notify(recipient: Recipient, message: Message): Promise<void> {
        const channel = this.channels.find(c => 
            c.supportsRecipientType(recipient.type)
        );
        
        if (!channel) {
            throw new NoChannelError(recipient.type);
        }
        
        await channel.send(recipient, message);
    }
}
 
// Usage - completely extensible:
const notifier = new NotificationService([
    new EmailNotification(emailService),
    new SMSNotification(smsGateway),
    new PushNotification(pushService),
    new SlackNotification(slackClient),  // Added later, no code changes
]);

OCP Through Abstraction

The Open-Closed Principle is achieved through abstraction. The interface defines the extension point; implementations provide the extensions. This is why interface design is so critical—a well-designed interface enables OCP; a poorly designed one makes it impossible.

Real-World Stability Patterns

Let's examine patterns from real-world systems that have achieved remarkable interface stability while allowing radical implementation evolution:

Long-Lived Stable Interfaces

•POSIX File System API — Defined in the 1980s, still standard today. The same open(), read(), write(), close() interface works with SSDs, network drives, and cloud storage that didn't exist when it was designed.
•SQL — The query language defined in 1970s works with databases from PostgreSQL to cloud-native distributed systems. Implementation complexity increased 1000x; the interface remained recognizable.
•HTTP — HTTP/1.0 (1996) applications still work with HTTP/3 (2022). The core request-response model and method semantics remained stable while transport evolved completely.
•Java Collections Framework — The List, Set, Map interfaces from 1998 work unchanged with modern implementations using entirely different algorithms and data structures.

What Makes These Interfaces Last?

Quality	Explanation
Domain-focused	They model the essential problem (files, data, requests), not technology
Operation-based	They define operations, not implementation mechanisms
Minimal	They expose only necessary operations, not optional conveniences
Technology-agnostic	No mention of specific storage, transport, or algorithms
Contract-complete	The semantic contract is clear and comprehensive

Applying These Lessons:

When designing your own interfaces for stability:

Ask what problem you're solving, not what technology you're using
Define the minimal set of operations needed to solve that problem
Document the semantic contract completely and explicitly
Avoid implementation concepts in names, parameters, or return types
Design extension mechanisms (optional parameters, strategy injection) upfront

Anti-Patterns: Unstable Interfaces

Understanding what makes interfaces unstable helps you avoid common design mistakes:

Interface Stability Anti-Patterns

•Technology Leakage — Interface mentions specific technologies (SQL, Redis, Kafka) that might be replaced. When technology changes, the interface breaks.
•Premature Optimization Exposure — Interface exposes optimization-specific methods (setBatchSize, enableCaching). Optimizations change; clients shouldn't know about them.
•Implementation Inheritance — Abstract class where subclasses must call super() in specific ways. Changes to base class break all subclasses.
•Configuration as Interface — Interface has methods for every configuration option. Configuration should be injected, not exposed.
•Protocol Coupling — Interface assumes specific communication protocol (HTTP, gRPC). Protocol changes break the interface.
•State Machine Exposure — Interface requires specific call order (init() then configure() then start()). Initialization is implementation detail.

unstable-interface.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// ❌ UNSTABLE: Technology leakage
interface UserCache {
    // Redis-specific concepts exposed
    getFromRedis(key: string): Promise<string>;
    setWithRedisExpiry(
        key: string, 
        value: string, 
        expirySeconds: number
    ): Promise<void>;
    configureRedisCluster(
        nodes: string[]
    ): void;
}
 
// ❌ UNSTABLE: Configuration as interface
interface MessageQueue {
    setKafkaBrokers(brokers: string[]): void;
    setConsumerGroup(group: string): void;
    setPartitionCount(count: number): void;
    // Every config option = interface churn
}

stable-interface.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// ✅ STABLE: Domain-focused
interface UserCache {
    // No mention of Redis
    get(userId: UserId): Promise<User | null>;
    set(user: User, ttl?: Duration): Promise<void>;
    invalidate(userId: UserId): Promise<void>;
}
 
// ✅ STABLE: Configuration injected
interface MessageQueue {
    send(message: Message): Promise<void>;
    subscribe(
        handler: MessageHandler
    ): Subscription;
}
 
// Configuration is constructor concern:
const queue = new KafkaQueue(kafkaConfig);
// Or via factory:
const queue = QueueFactory.create(config);

The 10-Year Test

Ask yourself: 'Would this interface still make sense if I rewrote the implementation in 10 years with technology that doesn't exist yet?' If yes, you've achieved stability. If no, you've leaked implementation assumptions.

Summary: Stable Interfaces, Flexible Implementations

Designing interfaces that remain stable while enabling implementation flexibility is the hallmark of mature software architecture. Let's consolidate the key principles:

Key Takeaways

•Contracts have three layers — Syntactic (signatures), semantic (behavior), and pragmatic (performance). Document all three for true stability.
•Focus on domain, not technology — Interfaces using domain concepts survive technology changes. Avoid leaking implementation specifics.
•Design extension points deliberately — Optional parameters, interface extension, strategy injection, and plugins enable growth without breakage.
•Use additive versioning — Add new capabilities without removing old ones. Deprecate with sunset periods before major version removals.
•Apply the Open-Closed Principle — Stable interfaces are closed for modification, open for extension through new implementations.
•Learn from long-lived interfaces — POSIX, SQL, HTTP show that minimal, domain-focused, technology-agnostic interfaces last decades.
•Avoid stability anti-patterns — Technology leakage, configuration exposure, and protocol coupling create fragile interfaces.

What's Next:

We've learned to identify boundaries, hide implementations, and design stable interfaces. The final piece is understanding how abstraction applies across architectural layers—from individual classes to entire systems. The next page explores abstraction in layered design, showing how these principles scale to complex architectures.

Page Complete

You now understand how to design interfaces that remain stable over time while allowing complete implementation flexibility. This skill enables you to build systems that evolve gracefully without breaking their clients.

3 / 4

Loading learning content...

System Design (LLD)Designing for Abstraction

Designing for Abstraction

LevelIntermediate

Duration60 mins

TopicDesigning for Abstraction

3 / 4

Stable Interfaces, Flexible Implementations

The Stability-Flexibility Paradox

This page teaches you to design interfaces with this durability—interfaces that will survive the evolution of your implementations.

What You Will Learn

The Interface-Implementation Contract

The Three Layers of a Contract:

Contract Layers
Layer	Description	Stability Requirement
Syntactic	Method signatures, types, parameters	Must never break (compilation errors)
Semantic	What methods do, their meaning	Must never change meaning (logic errors)
Pragmatic	Performance characteristics, resource usage	Should be documented if guaranteed

Pragmatic Stability is often implicit. If clients rely on findById being O(1), changing it to O(n) breaks their performance assumptions. Document pragmatic guarantees when they matter.

contract-layers.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
/**
 * UserRepository - Persistent storage for User entities.
 * 
 * SYNTACTIC CONTRACT: (enforced by compiler)
 *   The method signatures below define the syntactic contract.
 * 
 * SEMANTIC CONTRACT: (enforced by documentation and tests)
 *   - findById returns the user with the exact id requested, or null
 *   - save is idempotent: saving the same user twice has no side effects
 *   - delete removes the user permanently; future findById returns null
 *   - All operations are atomic: they fully succeed or fully fail
 * 
 * PRAGMATIC CONTRACT: (performance characteristics)
 *   - findById: O(1) average case, may require network roundtrip
 *   - save: O(1) amortized, writes are durable after return
 *   - list: O(n) where n is result size, paginated
 */
interface UserRepository {
    /**
     * Retrieves a user by their unique identifier.
     * 
     * @param id - The user's unique identifier
     * @returns The user if found, null if no user exists with this id
     * @throws InvalidIdError if id format is invalid
     */
    findById(id: UserId): Promise<User | null>;
    
    /**
     * Persists a user to storage.
     * 
     * IDEMPOTENCY: Calling save(user) multiple times with the same user
     * has the same effect as calling it once.
     * 
     * @param user - The user to save (new or existing)
     * @throws ValidationError if user data is invalid
     */
    save(user: User): Promise<void>;
    
    /**
     * Permanently removes a user from storage.
     * 
     * @param id - The identifier of the user to delete
     * @returns true if user was deleted, false if user didn't exist
     */
    delete(id: UserId): Promise<boolean>;
    
    /**
     * Lists users with pagination support.
     * 
     * @param options - Pagination options (limit, offset)
     * @returns Array of users, may be empty
     */
    list(options?: { limit?: number; offset?: number }): Promise<User[]>;
}
 
// The contract is explicit and comprehensive.
// Implementations can vary wildly while honoring this contract:
 
class PostgresUserRepository implements UserRepository { /* ... */ }
class MongoUserRepository implements UserRepository { /* ... */ }
class InMemoryUserRepository implements UserRepository { /* ... */ }
class CachedUserRepository implements UserRepository { /* ... */ }

Document the Semantics

Designing for Stability

Principles for Stable Interface Design

•Focus on Capabilities, Not Mechanisms — Define what clients can do, not how it's done. 'send a message' vs 'add message to queue and poll for delivery confirmation'.
•Use Domain Language — Interfaces using domain terms (Order, Customer, Invoice) are more stable than those using technical terms (Record, Row, Blob).
•Avoid Leaking Implementation Concepts — If changing the implementation would require interface changes, you've leaked. Don't mention SQL, JSON, or specific technologies.
•Prefer Composition Over Features — Small, composable interfaces are more stable than large, feature-rich ones. You can combine simple interfaces; you can't split complex ones.
•Design for the Invariant — Identify what must always be true, regardless of implementation. Design the interface to enforce these invariants.

Case Study: Payment Processing

Consider designing a payment interface. What's essential, and what's implementation detail?

Implementation-Leaking Design

•chargeStripeCard(token: string)
•set3DSecureEnabled(enabled: boolean)
•setWebhookUrl(url: string)
•getStripeCustomerId(): string
•Exposes Stripe-specific concepts
•Can't switch providers without changes

Stable Domain-Focused Design

•charge(amount: Money, method: PaymentMethod)
•refund(paymentId: PaymentId, amount?: Money)
•getPayment(id: PaymentId): Payment
•listPayments(filter: PaymentFilter)
•Uses domain concepts only
•Works with any provider

The Stability Test:

Ask: "If I completely rewrote the implementation using different technology, could I keep this interface?" If yes, your interface is stable. If no, you've leaked implementation details.

Extension Points and Flexibility

Optional parameters allow adding capabilities without breaking existing calls.

// Version 1.0
interface OrderService {
    createOrder(items: OrderItem[]): Promise<Order>;
}

// Version 1.1 - backward compatible!
interface OrderService {
    createOrder(
        items: OrderItem[], 
        options?: {
            priority?: 'standard' | 'express';  // New!
            giftWrap?: boolean;                 // New!
        }
    ): Promise<Order>;
}

// All existing callers still work:
await service.createOrder(items);

// New callers can use new features:
await service.createOrder(items, { priority: 'express' });

Best Practices:

Place all optional parameters in an options object (easier to extend)
Provide sensible defaults for all options
Document default behavior explicitly
Never require new options for existing use cases

Versioning Strategies

Even the best-designed interface eventually needs to change. Versioning strategies manage this evolution while maintaining backward compatibility for existing clients.

The Compatibility Spectrum:

Types of Changes and Their Impact
Change Type	Example	Impact	Version Bump
Additive	New optional parameter	None—existing code works	Minor (1.0 → 1.1)
Behavioral	Performance improvement	None if contract unchanged	Patch (1.0.0 → 1.0.1)
Deprecation	Mark method as deprecated	Warning only	Minor (1.1 → 1.2)
Breaking	Remove method, change signature	Compilation failure	Major (1.x → 2.0)

Strategies for Non-Breaking Evolution:

1. Additive-Only Changes

The safest evolution: only add, never modify or remove.

// Version 1.0
interface Cache {
    get(key: string): Promise<string | null>;
    set(key: string, value: string): Promise<void>;
}

// Version 1.1 - additive only
interface Cache {
    get(key: string): Promise<string | null>;
    set(key: string, value: string): Promise<void>;
    // NEW: optional TTL parameter
    setWithTTL?(key: string, value: string, ttlSeconds: number): Promise<void>;
    // NEW: batch operations
    getMany?(keys: string[]): Promise<Map<string, string>>;
}

2. Deprecation with Sunset Period

interface UserService {
    /**
     * @deprecated since 1.2.0 - Use findByIdentifier instead.
     * Will be removed in 2.0.0.
     */
    findByEmail(email: string): Promise<User | null>;
    
    // New preferred method
    findByIdentifier(identifier: UserIdentifier): Promise<User | null>;
}

3. Parallel Interfaces

// Original interface remains unchanged
interface PaymentProcessor {
    charge(amount: number, cardToken: string): Promise<ChargeResult>;
}

// New interface exists alongside, not replacing
interface PaymentProcessorV2 {
    charge(request: ChargeRequest): Promise<ChargeResult>;
    // Richer input, same contract
}

// Adapter allows gradual migration
class PaymentProcessorAdapter implements PaymentProcessor {
    constructor(private v2: PaymentProcessorV2) {}
    
    async charge(amount: number, cardToken: string): Promise<ChargeResult> {
        return this.v2.charge({ 
            amount: Money.fromCents(amount), 
            paymentMethod: PaymentMethod.fromToken(cardToken)
        });
    }
}

Breaking Changes Are Expensive

The Open-Closed Principle Connection

When you design a stable interface with implementation flexibility:

The interface is closed for modification (it doesn't change)
The system is open for extension (new implementations can be added)

This isn't coincidence—it's the essence of well-designed abstractions.

open-closed-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
67
// The interface is CLOSED - it won't change
interface NotificationChannel {
    send(recipient: Recipient, message: Message): Promise<SendResult>;
    supportsRecipientType(type: RecipientType): boolean;
}
 
// The system is OPEN - unlimited implementations can be added
 
class EmailNotification implements NotificationChannel {
    async send(recipient: Recipient, message: Message): Promise<SendResult> {
        // Email-specific implementation
        return this.emailService.send(recipient.email, message.toHTML());
    }
    
    supportsRecipientType(type: RecipientType): boolean {
        return type === RecipientType.EMAIL;
    }
}
 
class SMSNotification implements NotificationChannel {
    async send(recipient: Recipient, message: Message): Promise<SendResult> {
        // SMS-specific implementation
        return this.smsGateway.send(recipient.phone, message.toPlainText());
    }
    
    supportsRecipientType(type: RecipientType): boolean {
        return type === RecipientType.PHONE;
    }
}
 
class PushNotification implements NotificationChannel {
    async send(recipient: Recipient, message: Message): Promise<SendResult> {
        // Push notification implementation
        return this.pushService.send(recipient.deviceToken, message.toNotification());
    }
    
    supportsRecipientType(type: RecipientType): boolean {
        return type === RecipientType.DEVICE;
    }
}
 
// Adding Slack, Teams, WhatsApp, etc. requires ZERO changes to existing code.
// The interface is stable; implementations are flexible.
 
class NotificationService {
    constructor(private channels: NotificationChannel[]) {}
    
    async notify(recipient: Recipient, message: Message): Promise<void> {
        const channel = this.channels.find(c => 
            c.supportsRecipientType(recipient.type)
        );
        
        if (!channel) {
            throw new NoChannelError(recipient.type);
        }
        
        await channel.send(recipient, message);
    }
}
 
// Usage - completely extensible:
const notifier = new NotificationService([
    new EmailNotification(emailService),
    new SMSNotification(smsGateway),
    new PushNotification(pushService),
    new SlackNotification(slackClient),  // Added later, no code changes
]);

OCP Through Abstraction

Real-World Stability Patterns

Let's examine patterns from real-world systems that have achieved remarkable interface stability while allowing radical implementation evolution:

Long-Lived Stable Interfaces

•POSIX File System API — Defined in the 1980s, still standard today. The same open(), read(), write(), close() interface works with SSDs, network drives, and cloud storage that didn't exist when it was designed.
•SQL — The query language defined in 1970s works with databases from PostgreSQL to cloud-native distributed systems. Implementation complexity increased 1000x; the interface remained recognizable.
•HTTP — HTTP/1.0 (1996) applications still work with HTTP/3 (2022). The core request-response model and method semantics remained stable while transport evolved completely.
•Java Collections Framework — The List, Set, Map interfaces from 1998 work unchanged with modern implementations using entirely different algorithms and data structures.

What Makes These Interfaces Last?

Quality	Explanation
Domain-focused	They model the essential problem (files, data, requests), not technology
Operation-based	They define operations, not implementation mechanisms
Minimal	They expose only necessary operations, not optional conveniences
Technology-agnostic	No mention of specific storage, transport, or algorithms
Contract-complete	The semantic contract is clear and comprehensive

Applying These Lessons:

When designing your own interfaces for stability:

Ask what problem you're solving, not what technology you're using
Define the minimal set of operations needed to solve that problem
Document the semantic contract completely and explicitly
Avoid implementation concepts in names, parameters, or return types
Design extension mechanisms (optional parameters, strategy injection) upfront

Anti-Patterns: Unstable Interfaces

Understanding what makes interfaces unstable helps you avoid common design mistakes:

Interface Stability Anti-Patterns

•Technology Leakage — Interface mentions specific technologies (SQL, Redis, Kafka) that might be replaced. When technology changes, the interface breaks.
•Premature Optimization Exposure — Interface exposes optimization-specific methods (setBatchSize, enableCaching). Optimizations change; clients shouldn't know about them.
•Implementation Inheritance — Abstract class where subclasses must call super() in specific ways. Changes to base class break all subclasses.
•Configuration as Interface — Interface has methods for every configuration option. Configuration should be injected, not exposed.
•Protocol Coupling — Interface assumes specific communication protocol (HTTP, gRPC). Protocol changes break the interface.
•State Machine Exposure — Interface requires specific call order (init() then configure() then start()). Initialization is implementation detail.

unstable-interface.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// ❌ UNSTABLE: Technology leakage
interface UserCache {
    // Redis-specific concepts exposed
    getFromRedis(key: string): Promise<string>;
    setWithRedisExpiry(
        key: string, 
        value: string, 
        expirySeconds: number
    ): Promise<void>;
    configureRedisCluster(
        nodes: string[]
    ): void;
}
 
// ❌ UNSTABLE: Configuration as interface
interface MessageQueue {
    setKafkaBrokers(brokers: string[]): void;
    setConsumerGroup(group: string): void;
    setPartitionCount(count: number): void;
    // Every config option = interface churn
}

stable-interface.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// ✅ STABLE: Domain-focused
interface UserCache {
    // No mention of Redis
    get(userId: UserId): Promise<User | null>;
    set(user: User, ttl?: Duration): Promise<void>;
    invalidate(userId: UserId): Promise<void>;
}
 
// ✅ STABLE: Configuration injected
interface MessageQueue {
    send(message: Message): Promise<void>;
    subscribe(
        handler: MessageHandler
    ): Subscription;
}
 
// Configuration is constructor concern:
const queue = new KafkaQueue(kafkaConfig);
// Or via factory:
const queue = QueueFactory.create(config);

The 10-Year Test

Summary: Stable Interfaces, Flexible Implementations

Designing interfaces that remain stable while enabling implementation flexibility is the hallmark of mature software architecture. Let's consolidate the key principles:

Key Takeaways

•Contracts have three layers — Syntactic (signatures), semantic (behavior), and pragmatic (performance). Document all three for true stability.
•Focus on domain, not technology — Interfaces using domain concepts survive technology changes. Avoid leaking implementation specifics.
•Design extension points deliberately — Optional parameters, interface extension, strategy injection, and plugins enable growth without breakage.
•Use additive versioning — Add new capabilities without removing old ones. Deprecate with sunset periods before major version removals.
•Apply the Open-Closed Principle — Stable interfaces are closed for modification, open for extension through new implementations.
•Learn from long-lived interfaces — POSIX, SQL, HTTP show that minimal, domain-focused, technology-agnostic interfaces last decades.
•Avoid stability anti-patterns — Technology leakage, configuration exposure, and protocol coupling create fragile interfaces.

What's Next:

Page Complete

3 / 4