Interfaces as Software Contracts: Designing Boundaries That Last
An interface is easy to declare and hard to design. Five method signatures can compile while leaving every important promise unstated: whether calls are idempotent, how errors are classified, whether results are ordered, what “saved” means, and which changes remain compatible. Durable boundaries emerge when teams treat an interface as an agreement about observable behavior rather than a language feature.
Consider a shipping use case that asks a carrier gateway to create a label. The first implementation wraps one carrier's SDK. If the interface accepts that SDK's ShipmentRequest and returns its LabelResponse, the business layer is coupled even though the class has an I prefix. A lasting contract begins with what the caller needs: purchase shipment for a parcel, receive a label and tracking identifier, and distinguish rejection from an uncertain network outcome.
Design from the consumer backward
Start at the use case. Write the decision it must make after each outcome. The warehouse workflow may retry an unavailable carrier, ask an operator to correct an invalid address, or stop when the result is indeterminate because the carrier might already have purchased a label. Those branches reveal a contract more accurately than the provider documentation.
type PurchaseLabelResult =
| { kind: 'purchased'; label: Uint8Array; trackingNumber: string }
| { kind: 'rejected'; reasons: readonly string[] }
| { kind: 'temporarily_unavailable'; retryAfter?: Date }
| { kind: 'outcome_unknown'; correlationId: string };
interface ShipmentPurchaser {
purchaseLabel(
shipment: Shipment,
idempotencyKey: string
): Promise<PurchaseLabelResult>;
}This code block demonstrates a discriminated result contract. It uses business vocabulary and makes uncertainty first-class, forcing callers to handle every meaningful outcome. An adapter translates each carrier protocol into these cases. The interface does not expose HTTP status codes because the use case should not know that one implementation uses HTTP and another submits files to a legacy exchange.
The TypeScript handbook explains structural contracts at the type level, but structural compatibility alone is insufficient. Two implementations may accept and return the same shapes while disagreeing on durability, side effects, or error behavior. Document those semantics beside the contract and enforce what can be enforced with shared tests.
Name the capability and its owner
Technology names age quickly. CarrierApiClient, SqlOrderRepository, and KafkaPublisher describe current mechanisms. ShipmentPurchaser, OrderStore, and BusinessEventPublisher describe capabilities. Capability names keep the dependency pointed toward the consumer's policy and make replacement plausible.
Ownership is equally important. The team that owns the consuming policy should usually own the abstraction. If the carrier integration team publishes a generic interface mirroring its SDK, every consumer inherits its concepts. When warehouse policy owns ShipmentPurchaser, the carrier adapter depends inward on the contract it fulfills. This is dependency inversion in concrete organizational form.
Do not force one universal contract on consumers with different needs. Quoting shipment prices and purchasing labels may have different availability, latency, and consistency requirements. A batch reconciliation process needs pagination and historical retrieval that an interactive checkout does not. Separate client-specific contracts can share internal adapter code without pretending their promises are identical.
Put failures in the type system
Many weak interfaces return null or throw a general exception. The caller cannot tell “not found” from “database unavailable,” and retry code ends up parsing messages. Define failures that lead to different caller behavior. This can be a result type, documented exception set, or language-specific sealed hierarchy.
Avoid turning every infrastructure detail into a domain error. ConnectionResetByPeer is useful in adapter logs, not checkout policy. Translate it to a stable category such as TemporarilyUnavailable while preserving the original cause and correlation data for diagnostics. Translation is not information destruction: detailed technical context belongs in telemetry; stable decision categories belong in the interface.
Be explicit about partial success. A payment authorization can succeed remotely while the response is lost. A naive Timeout result encourages a retry that may double-charge. An OutcomeUnknown result forces reconciliation using an idempotency key or status query. Interfaces that model distributed reality are more valuable than interfaces that merely make mocking convenient.
Data shapes are part of the promise
Contract values should prevent invalid states where practical. Replace string currency with a Money value that binds amount and currency. Distinguish an unvalidated address from a normalized deliverable address. Use opaque identifiers instead of interchangeable strings. These choices communicate invariants and reduce repeated defensive code.
At the same time, avoid copying an entire domain object across a boundary. A notification sender probably needs recipient, template, locale, and template data—not a mutable Customer aggregate. Narrow inputs reduce coupling and accidental data exposure. They also make privacy review easier because the contract shows exactly what leaves a module.
Version data intentionally. Adding an optional response field is often compatible, while changing a unit from cents to decimal currency is not. For in-process interfaces, compiler errors help locate consumers, but runtime deployments can still be staggered. For HTTP, messaging, or plug-in contracts, define tolerance rules: readers ignore unknown fields, required fields are never repurposed, and semantic changes receive new names or versions. Microsoft's REST API Guidelines provide broad guidance on consistency and evolvability for network-facing contracts.
Contracts across processes are protocols
An in-memory function call can rely on one transaction and one deployment. A remote interface cannot. Once a boundary crosses a process, the contract includes authentication, serialization, timeouts, retries, rate limits, delivery semantics, and observability. Calling an HTTP client an implementation detail does not make these concerns disappear.
For a command endpoint, specify idempotency. Does the server retain keys, for how long, and against which identity? For a query, specify pagination stability and maximum staleness. For an event, specify the event's meaning, partition key, ordering scope, and duplicate behavior. The AsyncAPI specification is useful for describing message channels and payloads, but teams must still document business semantics that schema tools cannot infer.
Treat service-level expectations separately from functional types. A repository interface might promise correct version checks; its production adapter also has latency and availability objectives. Test and monitor both. A type checker cannot prove a p99 latency budget.
Build a contract test suite
A shared contract suite should run against every meaningful implementation, including fakes. For OrderStore, seed a fresh store through public operations, then verify create, read, conflict, deletion policy, ordering, and transaction behavior. Do not assert private SQL or method call counts. Assert what a consumer can observe.
export function orderStoreContract(name: string, makeStore: StoreFactory): void {
describe(name, () => {
it('detects a stale expected version', async () => {
const store = await makeStore();
const saved = await store.create(exampleOrder());
await store.save(saved.order.changeAddress(newAddress), saved.version);
await expect(
store.save(saved.order.cancel(), saved.version)
).rejects.toBeInstanceOf(VersionConflict);
});
});
}This code block demonstrates one shared, observable concurrency promise. Run the suite against an in-memory implementation during unit tests and a containerized database in integration tests. If the fake cannot model concurrency, say so and exclude it from tests that require that guarantee; do not silently weaken the contract. A fake that always succeeds can make application tests lie.
Provider adapters need additional protocol tests. Record representative sandbox responses or use a local stub to produce throttling, malformed payloads, delayed responses, and connection loss after submission. Periodically run a smaller compatibility suite against the real provider sandbox. Consumer-driven contract tools can help coordinate independently deployed services, but they supplement rather than replace semantic review.
Evolve without surprising callers
Before changing a contract, classify the change. A new optional operation may be source-compatible but still burden implementations. A new required result variant forces callers to consider a case and is deliberately breaking. Tightening validation may break callers that relied on previously accepted input. Changing retries can alter load and side effects even when signatures remain identical.
Use parallel change for significant migrations. Add the new capability, adapt implementations, migrate consumers, observe usage, and then remove the old path. For external protocols, publish a deprecation window and measure traffic by version. For internal monorepos, do not assume one commit makes runtime deployment atomic; queues and stored records can outlive code versions.
An architecture decision record should capture consequential promises: why the boundary exists, who owns it, consistency and idempotency semantics, and what would trigger a new version. This is more useful than generated API documentation alone.
Keep interfaces honest in production
Operations reveal contract violations that tests miss. Instrument outcomes in contract terms: purchased, rejected, temporarily unavailable, or unknown. Track adapter-specific status separately. Alert on impossible transitions, such as two tracking numbers for one idempotency key. Log contract version and correlation identifiers at process boundaries.
Budget timeouts. The caller's deadline should constrain downstream attempts; an adapter should not start a thirty-second retry when only two seconds remain. Apply bounded retries only to operations known to be safe. Circuit breakers and bulkheads may protect resources, but they change visible failure modes and therefore belong in contract discussions.
Review interfaces when production workarounds accumulate. If callers inspect error text, branch on implementation type, or request the concrete client “just for one field,” the abstraction is missing a needed promise or serving incompatible consumers. Do not patch over these signals with casts. Revisit the boundary.
Common ways boundaries decay
The first failure is a vendor-shaped interface. It changes whenever the vendor does and leaks transport details inward. The second is the “god gateway,” built to avoid multiple integrations but so broad that no implementation can satisfy it coherently. The third is a marker interface with no behavioral promise; it creates ceremony without substitutability.
Another failure is accidental compatibility. Teams add optional fields indefinitely, then discover that old consumers interpret absence incorrectly. Or they publish events named OrderUpdated whose meaning depends on hidden database fields. Specific business events and explicit defaults age better. Event-Driven Architecture explores durable event meaning and workflow reliability.
Finally, mocks can ossify implementation assumptions. If a test expects exactly two repository calls in a particular order, a harmless batching change breaks it. Prefer observable state and result assertions. The principles in Composition Over Inheritance can also help implementations assemble behavior without expanding public contracts.
A boundary is successful when it permits disagreement
A strong interface allows implementations to differ internally while agreeing on what consumers can observe. It names a capability in client language, represents decision-relevant failures, constrains data and side effects, and states distributed-system semantics where necessary. Its tests validate those promises against reality.
The goal is not to freeze an API forever. Lasting boundaries evolve deliberately: compatible additions where semantics remain stable, explicit versions where they do not, and measured migrations instead of surprises. Design from the consumer backward, keep ownership clear, and let operational evidence challenge the contract. That is how an interface becomes an architectural boundary rather than an extra file. Additional design and implementation material is available in /resources.
