# Maven-API vs Maven-Impl Modules: Understanding the Apache Maven 4 Architecture

> Understand the Maven 4 architecture by exploring the difference between maven-api and maven-impl modules. Learn how contracts and implementations work together.

- Repository: [The Apache Software Foundation/maven](https://github.com/apache/maven)
- Tags: internals
- Published: 2026-07-07

---

**The `maven-api` modules expose the public, immutable contracts that third-party code can depend on, while the `maven-impl` modules supply the concrete runtime implementations that fulfill those contracts.**

Apache Maven 4 restructured its codebase in the `apache/maven` repository to enforce a strict boundary between stable public interfaces and internal implementation details. The **maven-api and maven-impl** module groups form the two halves of this architecture, allowing plugin developers to compile against guaranteed-stable APIs while the Maven core team evolves the engine internals without breaking external contracts.

## What Is maven-api?

The **maven-api** aggregate module defines the public, immutable Maven 4 API. According to the source tree at [`api/pom.xml`](https://github.com/apache/maven/blob/main/api/pom.xml), this group contains only interfaces, value objects, and service-provider contracts—never concrete implementation logic. This strict boundary ensures that external code can safely rely on these types without exposure to internal engine changes.

### Core API Sub-Modules

The API aggregate organizes functionality into focused sub-modules:

- **maven-api-annotations** – Annotation definitions used throughout the API
- **maven-api-di** – Dependency injection abstractions (e.g., `@Inject`)
- **maven-api-xml**, **maven-api-model**, **maven-api-settings**, **maven-api-toolchain** – Immutable model objects representing POMs, settings, and toolchains
- **maven-api-core**, **maven-api-spi**, **maven-api-cli** – Core service-provider interfaces for project building, repository systems, and CLI operations

## What Is maven-impl?

The **maven-impl** aggregate module, declared in [`impl/pom.xml`](https://github.com/apache/maven/blob/main/impl/pom.xml), supplies the concrete implementations of the API contracts. This is where the actual Maven engine, dependency injection container, XML parsers, and command-line interface reside. All mutable runtime state and wiring logic lives here rather than in the API.

### Implementation Components

Key sub-modules within the implementation aggregate include:

- **maven-core** – The real Maven build engine handling sessions, execution, and plugin management (contains `org.apache.maven.execution.MavenSession`)
- **maven-logging**, **maven-jline** – Logging infrastructure and console support
- **maven-di** – The default DI container (Sisu) that wires API implementations together
- **maven-xml** – XML handling utilities used by the core
- **maven-cli** – The `mvn` command-line driver
- **maven-testing** – Test harness for the implementation

## Key Differences Between Maven-API and Maven-Impl

Understanding the **maven-api vs maven-impl** distinction requires examining four architectural boundaries:

**Contract vs Realization**
The maven-api modules expose *what* Maven can do through interfaces like `ModelBuilder`, while maven-impl provides *how* it is done through concrete classes such as `MavenSession`.

**Immutability Guarantees**
API modules enforce immutability in value objects (`Model`, `Settings`) to prevent external code from modifying internal state, whereas implementation classes in `impl/maven-core` manage mutable runtime state during builds.

**Dependency Direction**
Code in `impl/` depends on `api/`, but never the reverse. This ensures the API remains free of implementation details and circular references.

**Service Provider Pattern**
The API defines service interfaces (e.g., `org.apache.maven.api.services.ModelBuilder` in [`api/maven-api-model/src/main/java/org/apache/maven/api/services/ModelBuilder.java`](https://github.com/apache/maven/blob/main/api/maven-api-model/src/main/java/org/apache/maven/api/services/ModelBuilder.java)) that the implementation fulfills, allowing runtime discovery via the DI container.

## Practical Code Examples

### Consuming the Stable API

When writing plugins or tools that need to parse POMs without embedding the full Maven runtime, depend only on the API. The following example uses the `ModelBuilder` interface:

```java
// API only – no Maven core classes are referenced
import org.apache.maven.api.model.Model;
import org.apache.maven.api.services.ModelBuilder;
import org.apache.maven.api.services.ModelBuilderException;
import org.apache.maven.api.services.ModelSource;

ModelBuilder modelBuilder = serviceLocator.lookup(ModelBuilder.class);
Model model = modelBuilder.build(
        ModelSource.fromPath(Paths.get("pom.xml")),
        new ModelBuilderRequest()
).getModel();

```

This code compiles against the **maven-api** modules alone and works with any compliant Maven 4 implementation.

### Using Implementation Classes

To execute a full build, you must use the concrete implementation classes from [`impl/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java) and the CLI driver:

```java
// Implementation – uses Maven core classes
import org.apache.maven.execution.MavenSession;
import org.apache.maven.cli.MavenCli;

public class BuildRunner {
    public static void main(String[] args) throws Exception {
        MavenCli cli = new MavenCli();
        // The CLI internally creates a MavenSession (implementation)
        int result = cli.doMain(new String[] {"clean", "install"}, 
                                new File(".").getAbsolutePath(), 
                                System.out, System.out);
        System.exit(result);
    }
}

```

This approach brings in the **maven-impl** modules and initializes the complete Maven engine including Sisu DI wiring and logging infrastructure.

## Summary

- **maven-api** defines immutable contracts, interfaces, and value objects in [`api/pom.xml`](https://github.com/apache/maven/blob/main/api/pom.xml) that guarantee backward compatibility for plugin developers.
- **maven-impl** provides the concrete build engine, CLI, and DI container declared in [`impl/pom.xml`](https://github.com/apache/maven/blob/main/impl/pom.xml) that realizes the API contracts at runtime.
- The separation allows third-party code to depend only on the stable API while the Maven core team evolves implementation details in the impl modules.
- API classes like `org.apache.maven.api.services.ModelBuilder` expose functionality without implementation details, whereas `org.apache.maven.execution.MavenSession` in the impl module manages mutable build state.

## Frequently Asked Questions

### Can I depend on maven-impl in my Maven plugin?

No. You should declare dependencies only on **maven-api** modules. The `maven-impl` classes represent internal implementation details that can change between releases. Relying on them creates brittle plugins that may break when the Maven core updates its internal structure.

### What dependency injection framework does maven-impl use?

The **maven-impl** module uses **Sisu** as its default DI container, configured in the `maven-di` submodule. This container wires together the API interfaces with their concrete implementations at runtime, satisfying injection points defined in `maven-api-di`.

### Are maven-api classes backward compatible across Maven 4 versions?

Yes. The **maven-api** modules are designed as stable, immutable contracts specifically to guarantee backward compatibility. According to the `apache/maven` source structure, these interfaces and value objects only change in major version releases, whereas `maven-impl` can evolve independently between maintenance releases.

### Where can I find the source for the ModelBuilder interface?

The `ModelBuilder` interface resides in [`api/maven-api-model/src/main/java/org/apache/maven/api/services/ModelBuilder.java`](https://github.com/apache/maven/blob/main/api/maven-api-model/src/main/java/org/apache/maven/api/services/ModelBuilder.java) within the API module tree. In contrast, its runtime implementation lives in the implementation module, though external code should only reference the interface type.