Abstraction and Interfaces

Introduction

A payment service at a large e-commerce company calls chargeCard(amount, token). The engineers who wrote that call have no idea whether the underlying processor is Stripe, Braintree, or an internal gateway. They do not know whether the charge goes over REST or gRPC. They do not know whether there is a retry queue behind the scenes. They know one thing: they pass an amount and a token, and they get back a result. Three years later, the company switches processors. The payment service code does not change. That is what a good abstraction achieves.

Now consider the alternative. A different team wrote chargeStripe(amount, stripeToken, idempotencyKey, retryCount). When the processor changes, every caller changes. The implementation detail — Stripe — leaked through the interface into every system that depended on it. The abstraction failed.

Thread Activation

You have already seen encoding (T10) in Book 1 and Book 2, where data is transformed into a representation that hides internal structure — a hash hides the raw data, a compressed format hides the original bytes. Here the same pattern appears at code level. An abstraction encodes a capability: it presents a consistent interface that hides the complexity of implementation behind a stable surface. The shape is the same: what varies is concealed, what is stable is exposed.

The Concept

An abstraction is a simplified representation of something more complex. In code, an abstraction takes the form of an interface: a defined set of operations a component exposes, with no commitment about how those operations are implemented.

Three properties make an abstraction good. First, it hides irrelevant complexity. The caller of chargeCard does not need to know about retry logic, idempotency keys, or processor-specific error codes. Hiding this complexity is the primary job of the interface. Second, it exposes only what callers need. Every additional method or parameter in an interface is a commitment. Commitments are expensive — they constrain every future implementation. Third, it does not leak implementation details.

The Law of Leaky Abstractions states that every non-trivial abstraction eventually reveals implementation details. A database abstraction layer returns connection pool errors. A filesystem abstraction reveals OS-level path separators. A cloud storage abstraction exposes eventual consistency. The law does not mean abstractions are useless — it means abstractions require maintenance and that callers must be prepared for leakage under stress.

Interface design follows from these properties. A good interface is small (few methods), stable (it rarely changes), and complete (it supports everything callers legitimately need). An interface with twenty methods is either poorly bounded or covering too many responsibilities. An interface that changes every release forces every caller to change.

The cost of a bad abstraction is paid in coupling. When an implementation detail leaks through an interface, callers begin to depend on that detail. The implementation can no longer change without changing callers. What was meant to isolate change instead propagates change.

How It Works

Consider a storage abstraction:

interface BlobStore:
    method put(key: String, data: Bytes) -> Result
    method get(key: String) -> Result<Bytes>
    method delete(key: String) -> Result
    method exists(key: String) -> Boolean

Two implementations:

class LocalFileBlobStore implements BlobStore:
    method put(key, data):
        path = join(base_dir, key)
        write_file(path, data)
        return Success

    method get(key):
        path = join(base_dir, key)
        if not file_exists(path):
            return NotFound
        return read_file(path)

class S3BlobStore implements BlobStore:
    method put(key, data):
        s3_client.put_object(bucket, key, data)
        return Success

    method get(key):
        try:
            return s3_client.get_object(bucket, key)
        catch NoSuchKey:
            return NotFound

Callers depend on BlobStore. The choice of local disk or S3 is a deployment decision invisible to callers. Testing uses LocalFileBlobStore or an in-memory stub. Production uses S3BlobStore. The abstraction holds.

Where does it break? If S3BlobStore.put occasionally returns EventuallyConsistent — an S3-specific result type — and callers start to handle it, the abstraction has leaked. Now callers know about S3. Removing S3 requires changing callers. The interface has become a lie.

Tradeoffs

AT8 — Coupling/Cohesion: A well-designed abstraction reduces coupling by hiding implementation. Callers depend on the interface, not the implementation. This means implementations can change independently. The cost: the interface itself becomes a coupling point. Changing an interface requires changing every implementor and every caller. Good interfaces are therefore conservative — add methods rarely, remove methods never.

AT3 — Simplicity/Flexibility: A narrow interface is simple. A wide interface is flexible but harder to implement and harder to reason about. A BlobStore with four methods is easy to implement against any storage backend. A BlobStore with twenty methods — supporting metadata, tagging, versioning, lifecycle policies — is flexible but forces every implementor to cover the full surface, including implementors that only need the basics.

Where It Fails

FM8 — Schema/Contract Violation: When an interface changes without coordinating with callers, behaviour breaks at the boundary. A method renamed, a return type changed, an error semantics altered — these are contract violations. Callers compiled against the old contract fail at runtime. In loosely-typed systems or across service boundaries, these violations are silent until production.

FM2 — Cascading Failures: A leaky abstraction that exposes retry logic or timeout semantics can cause callers to implement their own retry strategies on top of the implementation’s retry strategies. Double-retry under failure amplifies load rather than protecting against it. The abstraction intended to simplify behaviour accidentally produced emergent failure behaviour.

Real Systems

POSIX filesystem interface: open, read, write, close — four operations that have abstracted every storage medium from magnetic tape to NVMe SSDs for fifty years. Implementations vary enormously; the interface has not changed. This is the canonical example of a stable, well-bounded abstraction.

JDBC (Java Database Connectivity): A standard interface for relational databases. Write once against Connection, Statement, ResultSet; run against MySQL, PostgreSQL, or Oracle. Leakage appears in SQL dialects (the abstraction does not cover query language) and in connection pool errors (implementation-specific failure modes surface through the generic interface).

Kubernetes API: kubectl apply submits a desired state manifest. The control plane — which may run on any cloud or on bare metal — reconciles reality toward that state. Callers know nothing about the underlying infrastructure. The abstraction is so successful that the same manifest deploys to AWS, GCP, or an on-premises cluster.

HTTP: The protocol abstracts TCP. Callers speak HTTP methods and status codes; they do not manage TCP handshakes or retransmission. Leakage occurs at connection limits, timeout configurations, and keep-alive behaviour — TCP details that surface under load.

Exercises