In a Gradle multi-module Kotlin or Java build, what's the difference between declaring a dependency with the api configuration versus the implementation configuration, and how does that difference help enforce API and implementation separation?

## The two configurations Gradle's `java-library` plugin introduces two dependency configurations with different visibility semantics. | Configuration | What it does to a consumer | |---|---| | `api` | A dependency declared api is exposed transitively: it appears on the compile classpath of every module that depends on the module declaring it. | | `implementation` | A dependency declared implementation is only added to that module's own compile and runtime classpath - it is not exposed to consumers at compile time, though it still ends up on the full runtime classpath transitively, since the application still needs it present to actually run. | The distinction is purely about what consumers need in order to compile against you, not about whether the dependency exists in the final assembled application. ## Why the distinction exists This exists primarily for **build performance** and **communication of intent** at scale. - Gradle's incremental compiler can use the api/implementation distinction to decide what needs recompiling: if you change the public signature of an implementation-only dependency, Gradle knows no downstream consumer compiled against that dependency in the first place, so none of them need to be recompiled - only the module that directly declared it does. On a large multi-module build with hundreds of modules, this can be the difference between a change triggering a handful of recompilations versus cascading through the entire dependency graph. - Beyond performance, the two keywords communicate developer intent directly in the build file: `api` says 'this is genuinely part of what I promise,' `implementation` says 'this is an internal detail, ignore it.' ## A build-time rule, not a runtime boundary The enforcement mechanism here is different in kind from JPMS: this is a build-time, compile-classpath visibility rule enforced by the build tool, not a JVM-level runtime boundary. Nothing stops code at runtime from reflectively reaching an implementation-only dependency's classes, because they are still physically present on the runtime classpath - the split is a compile-time convenience and performance mechanism, not a hard security or access-control boundary. This matters when comparing it to JPMS's `exports/opens`, which do enforce visibility at class-loading and reflection time. ## The trade-off The main trade-off is that this only works with discipline: 1. **Declaring everything api by default**, out of laziness or to avoid dealing with compile errors, defeats the purpose entirely - consumer builds slow down and unnecessary coupling creeps in, since every api dependency becomes part of what every consumer's classpath drags in. 2. **Going the other way, marking a dependency implementation** when one of its types actually appears in a public method signature produces a compile failure for every downstream consumer the moment they try to use that method, because the needed type simply isn't on their classpath - Gradle fails loudly rather than silently doing the wrong thing, which is a deliberately good failure mode, though it can confuse developers seeing an error about a class they never explicitly imported. ## A concrete real-world case A concrete real-world case: a module `reporting` depends on a PDF-generation library only to render report output internally, with no PDF-related type ever appearing in reporting's own public method signatures. Declaring that dependency implementation means a consumer module that only calls `reporting.generateSummary()`: - never sees the PDF library on its own compile classpath, - never needs to know it exists. And reporting's team can later swap PDF libraries entirely without touching any consumer. This mirrors, at the Gradle dependency-declaration level within a single module, the same goal that a dedicated api/impl module split achieves at the artifact level - and the two techniques compose naturally: a dedicated `foo-api` module can itself use api and implementation internally for its own dependencies, and a dedicated `foo-impl` module typically declares its dependency on foo-api itself as api, since foo-impl's own public classes implement foo-api's interfaces and therefore need to expose those types onward too. ## The JPMS analog It's also worth noting the direct JPMS analog, since both mechanisms solve a similar problem at different layers. | Declaration | Effect | |---|---| | `requires transitive` in a `module-info.java` file | Behaves like Gradle's api, exposing a dependency's exported packages onward to your own consumers so they don't need to separately require it themselves | | a plain `requires` | Behaves like implementation, pulling the dependency in for your own use without exposing it further | The key difference is that Gradle's api/implementation split is purely a build-tool convention checked at compile time within a Gradle-aware toolchain, while JPMS's `exports` and `requires transitive` are enforced by the JVM itself at module-resolution and class-loading time, independent of which build tool produced the jar. A team migrating from a plain classpath-based build to JPMS modules often finds that api dependencies map naturally onto requires transitive declarations, since both describe the same underlying question: what does this module promise to hand onward to whoever depends on it.