In a modularized mobile app, why should one feature depend only on another feature's API module rather than on its implementation module?
answer
- split the contract from the code
- small stable surface, large changing body
- edit the body, dependants stay built
- the app module picks the implementation
- no feature-to-feature implementation edges
basics
~20 sAn API module holds only a small, stable contract; the implementation module holds everything behind it. Depending on the API means implementation edits do not recompile other features, internals stay hidden, and the app module picks the implementation.
solid answer
~50 sA feature that others need is split in two. The **API module** carries only the contract: a few interfaces and plain models, such as the wallet's "list payment methods" and "charge" operations, and it changes rarely. The **implementation module** holds the screens, view models, data sources and everything else, and depends on its own API module. Other features depend on the API module only. Three things follow. An edit inside the wallet's implementation does not recompile the ride-hailing or food features, because nothing they compile against changed. The wallet team can refactor its internals freely, since nothing outside can see them. And no feature can grow a hidden coupling to another's internals. The **app module** is the only production module that depends on feature implementation modules, and it binds each one to its API, which is also where a test or demo build swaps in a fake.
code
pseudocode · 14 linesmodule wallet-api
interface payment_methods
list_for_current_user() -> list of payment_method
interface charges
charge(method_id, amount) -> charge_result
module wallet-impl depends on wallet-api, core-network
class real_charges implements charges // private screens, data sources
module ride depends on wallet-api // never on wallet-impl
module food depends on wallet-api
module app depends on ride, food, wallet-impl
bind charges -> real_chargesgo deeper
Recall the two halves: the API module is the small contract, the implementation module is the code behind it, and other features use only the contract.
Explain which modules rebuild for an implementation edit versus an API edit, and why the app module is the only production module that depends on feature implementations.
Decide where the split pays and where it is overhead, keep API modules free of UI and third-party types, and catch re-exported dependencies that widen the rebuild set.
Treat API modules as inter-team contracts: changes need the consuming teams' agreement, and the rule against implementation edges is enforced by the build, not by memory.
## The problem: a feature that depends on another feature's code In the super-app (ride-hailing, food delivery and a wallet in one binary, about 60 engineers in eight teams), the ride and food features both need to charge the user. The quick route is to let them depend on the wallet feature module directly. That edge has three costs: - **Build cost**: the ride and food modules now compile against the whole wallet module, so an edit to a wallet screen can recompile them too. - **Coupling**: they can use any public class in the wallet module, so over time they start depending on things the wallet team never meant to promise. - **Team friction**: the wallet team cannot reshape its internals without breaking two other teams. ## Splitting the contract from the code | | **API module** | **Implementation module** | |---|---|---| | Holds | Interfaces, plain data models, identifiers | Screens, view models, data sources, the real logic | | Size | Small | Large | | Changes | Rarely, and deliberately | Often | | Depends on | Little or nothing beyond basic core modules | Its own API module, plus core modules | | Depended on by | Other features, the app module | Only the app module, and tests | The implementation module **implements** the API. Other features **use** the API. Only the **app module**, the composition root that builds the object graph, depends on both and binds one to the other. Seen as a principle, this is dependency inversion applied at module granularity; the principle itself is a separate topic, and here the interest is what it does to the module graph. ## What it buys at build time An incremental build redoes the work whose inputs changed and the work downstream of it. Splitting API from implementation changes what is downstream: 1. **An edit inside the wallet implementation** (a layout, a bug fix, a new private helper): the wallet implementation module rebuilds and the app module repackages. The ride and food features compile only against the wallet API, which did not change, so they do not rebuild. 2. **An edit to the wallet API** (a new parameter on an interface): every module that depends on the API must recompile. That is the point of keeping it small and stable. 3. **A direct dependency on the implementation** (the edge this design forbids): the ride and food modules, and everything downstream of them, are now downstream of every wallet edit, so a wallet change can rebuild them, and any change to a public wallet class certainly does. The same reasoning applies to what a module re-exports. If a module makes its own dependencies part of its public surface, its consumers compile against those too, and a change in any of them ripples further. Keeping a module's own dependencies private unless a type genuinely appears in its contract narrows what each change can reach. ## What goes in the API module - Interfaces describing what other features may ask of this one. - Plain data models and **identifiers**, such as a payment-method id, rather than rich objects tied to the implementation. - Nothing from the UI layer: no screens and no view models, because those belong to the feature's own flow. - No third-party types if they can be avoided, because each one in the contract becomes something every consumer compiles against. ## When the split is worth it The split is not free: it is two modules instead of one and an indirection to bind. Apply it where it pays: - Other modules depend on the feature, especially across team boundaries. - More than one implementation exists or is wanted: real, fake for tests, a lightweight one for a demo build. - The codebase is large enough that build time and team autonomy matter. A leaf feature that nothing else depends on gains nothing from an API module. The rule to enforce is narrower than "split everything": **no module other than the app module may depend on a feature's implementation module.**
- What belongs in an API module, and what must stay out?Interfaces for what other features may ask of this one, plus plain data models and identifiers. Keep out UI, view models, data sources and third-party types: every type in the API module is compiled against by every dependant, so each extra one widens the surface whose changes force rebuilds and ties other teams to your internals.
- Does every module need an API and implementation split?No. Split where other modules depend on the feature, where several implementations exist, or where separate teams sit on either side. A leaf feature only the app module depends on gains nothing from an API module and still pays for it: one more module to configure and one more binding to maintain.
- Where does a fake implementation for tests come from in this design?A test or demo build binds the API to a different implementation module, often a fake that returns canned data. Because the features compile only against the API, they run unchanged against the fake, and no test needs the real wallet's network or storage.
- The API module should contain the feature's view models so other features can reuse them.
- An edit inside an implementation module recompiles every module in the app anyway.
- Depending on another feature's implementation is fine as long as there is no cycle.
- The API split exists only for testability and does nothing for build time.
- Every module, including leaves nobody depends on, must be split into API and implementation.