When designing a module's public API surface, what's the practical process for deciding what goes in the API versus what stays in the implementation, and what goes wrong when a team just exposes everything 'to be safe'?

## The practical process The practical process is **consumer-first design**. 1. You enumerate the operations external callers actually need - submit an order, look up an order's status - and define minimal interfaces and DTOs for exactly those operations, only implementing the supporting machinery afterward. 2. Every supporting class, such as repositories, mappers, internal validators, or retry helpers, stays inside the implementation module or an unexported package. 3. Any internal type that would otherwise need to cross the boundary, because it's a natural parameter or return type, either becomes a deliberate part of the API as a purpose-built DTO, or gets translated at the boundary - mapping an internal persistence entity to a public DTO right before returning it - so the internal representation never actually leaks. That translation step is deliberate extra ceremony, and skipping it is the single most common way implementation details end up leaking into a public API by accident. ## The underlying justification The underlying justification is **Hyrum's Law**: with a sufficient number of users of an API, it does not matter what you promise in the contract, because all observable behaviors of the system will eventually be depended on by somebody. - If a class is technically public and reachable, someone will eventually depend on it even if it's undocumented and never intended as part of the contract, especially inside a large monorepo with dozens of internal consumers. - Once that happens, the 'internal' code inherits all the compatibility obligations of real API code without anyone having chosen that outcome, and the team that owns it only discovers the tax the moment they try to change it and something downstream unexpectedly breaks. ## The trade-off The trade-off is real design time spent upfront: - translation and mapping layers, - more types to name and maintain, - and more review scrutiny on the question of whether a given type or method should be public at all. For a young module with a single caller, this can feel like premature bureaucracy. Exposing everything, by contrast, is **cheap today and expensive tomorrow**, because every additional exposed method or type is a near-permanent commitment - removing or changing it later becomes a breaking change requiring a deprecation cycle, a major version bump, or a coordinated multi-team migration. The right calibration usually tracks the number of independent consumers and how stable the module is expected to be: a module with one caller on the same team can reasonably start looser and tighten later, while a module published to many teams, or externally, needs the discipline from day one, because retrofitting it after real adoption is dramatically more expensive than getting it right up front. ## How it fails in production In production, this failure mode shows up as a kind of **paralysis**: a team discovers it cannot change an internal helper class because several other teams somehow ended up importing it directly, so a routine refactor stalls indefinitely or gets abandoned. - It can also show up as a module owner shipping what they believed was a minor internal change that quietly breaks unrelated consumers who never should have been coupled to that detail in the first place, eroding trust in the module's versioning promises. - And it shows up structurally when an API module grows monotonically over years, because it is always easier to add a public method than to remove one, until the 'public contract' is functionally identical to the entire codebase and the split delivers no benefit while still costing its full structural overhead. ## A concrete worked scenario A concrete worked scenario: a `notifications-api` module is used by a dozen internal microservices to send emails and text messages. Early on, someone exposes the internal `EmailTemplateEngine` class directly, because it's convenient for one consumer that wants custom formatting. Two years later, the notifications team wants to replace that engine with a faster templating library, only to discover that five separate services now construct `EmailTemplateEngine` instances directly, so the intended internal swap now requires a coordinated cross-team migration plan instead of a same-day refactor - exactly the coordination cost the api/impl split existed to eliminate, undone by one convenience exception years earlier. In hindsight, the correct fix would have been adding a narrow, purpose-built method to the real API, such as `sendWithCustomFormat(...)`, instead of exposing the internal engine wholesale. The general lesson generalizes well beyond this one scenario: every convenience exception made to avoid a small amount of design work today tends to compound, because each exception makes the next one look normal, and by the time the cost becomes visible it is spread across teams who never chose to take it on.