A payment service 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. 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: 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.
Three Properties That Make an Abstraction Good
Not every interface is an abstraction. An interface that exposes implementation details is a leaky pipe, not an abstraction layer. Three properties separate the good ones from the bad.
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 is the primary job. Every detail visible through the interface is a detail the caller now depends on.
Second: it exposes only what callers need. Every method or parameter in an interface is a commitment — to every caller, for as long as the interface exists. A BlobStore interface with four methods (put, get, delete, exists) is easy to implement against any storage backend. A BlobStore with twenty methods — metadata, tagging, versioning, lifecycle policies — forces every implementor to cover the full surface, including implementors that only need the basics.
Third: it does not leak implementation details. If S3BlobStore.get occasionally returns an EventuallyConsistent result type — an S3-specific concept — and callers start handling it, the abstraction has leaked. Now callers know about S3. Removing S3 requires changing callers. The interface has become a lie.
The Leaky Abstraction Problem
The Law of Leaky Abstractions (Spolsky) states that every non-trivial abstraction eventually reveals implementation details. TCP abstracts reliable packet delivery. But TCP timeouts, retransmissions, and window sizes surface when the network is congested. JDBC abstracts relational databases. But SQL dialects and connection pool errors surface under load.
This is not a failure of TCP or JDBC. It is the nature of abstraction at scale. The goal is not to make abstractions perfectly opaque — it is to make the common case simple and the rare case manageable. A well-designed interface fails in predictable, documented ways when the lower layer fails. A poorly designed one produces mysterious errors that require understanding three layers down to diagnose.
The Controlling Tradeoff: AT8
Adding an abstraction layer always trades one form of coupling for another. This is AT8 — Coupling vs. Cohesion.
Before the interface, callers are coupled to the implementation. Change the database and every caller changes. After the interface, callers are coupled to the interface instead. The implementation can change independently. But the interface itself is now a coupling point: change the interface and every implementor and every caller must change.
Good interfaces are therefore conservative. Add methods rarely. Remove methods never. Each addition is a new commitment to every caller, potentially forever.
There is also AT3 — Simplicity vs. Flexibility. A narrow interface with four methods is easy to implement against any backend. A wide interface with twenty methods is flexible but expensive: every implementor must cover the full surface. Choose the narrowest interface that satisfies legitimate caller needs.
The Failure Mode: FM8
When an interface changes without coordinating with callers, behaviour breaks at the boundary. FM8 — Schema/Contract Violation. A method renamed, a return type changed, error semantics altered — callers compiled against the old contract fail at runtime. In loosely-typed systems or across service boundaries, these violations are silent until production.
A second failure comes from leaky abstractions specifically. If the interface exposes retry logic and callers implement their own retries on top of it, a single downstream failure produces double-retry cascades. The abstraction intended to simplify behaviour produces emergent failure behaviour instead. This is FM2 — Cascading Failures — triggered by the interface design rather than the network.
In Practice
The canonical stable abstractions last decades. POSIX filesystem (open, read, write, close) has abstracted every storage medium from magnetic tape to NVMe SSDs since 1988 — nearly four decades without the interface changing. Kubernetes API (kubectl apply) submits a desired-state manifest that runs unchanged on AWS, GCP, or bare metal. HTTP abstracts TCP so completely that most engineers never touch a TCP socket directly.
Each of these is small (few operations), stable (rarely changes), and complete (covers what callers legitimately need). That combination is harder to design than it looks. Most interfaces start too wide, leak too much, and become expensive commitments.
The signal that an abstraction is failing: changing a subsystem requires changing callers who should not care about implementation details. When that happens, the interface has drawn the boundary in the wrong place — and every caller is paying the price.