# Exploring Maven API Modules for Developers: A Complete Guide to Maven 4's Modular Architecture

> Learn about Maven API modules in a complete guide for developers. Discover Maven 4's modular architecture enabling stable, versioned interfaces for tools and plugins.

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

---

**Apache Maven 4 re-architected its codebase into discrete API modules that provide a stable, versioned surface for tool and plugin developers, allowing compilation against lightweight artifacts without pulling in the heavy Maven runtime.**

Exploring Maven API modules for developers reveals how Maven 4 addresses long-standing extensibility challenges through a clean separation between public contracts and internal implementation. The `apache/maven` repository organizes these modules under the top-level `api/` directory, each distributed as an independent artifact following the naming convention `org.apache.maven:maven-api-<module>`. This modular design ensures that third-party tools can depend on specific functional areas—such as model parsing or dependency resolution—without inheriting the full execution environment.

## Maven API Module Catalog

Maven 4 exposes eleven distinct API modules, each targeting a specific domain of the build lifecycle. These modules form a directed acyclic graph where higher-level APIs depend only on lower-level contracts, never on implementation code.

### Core Model and Configuration APIs

- **maven-api-annotations**: Supplies compile-time annotations like `@Component` and `@Parameter` for describing Maven components. Located at [`api/maven-api-annotations/src/main/java/org/apache/maven/api/annotations/Component.java`](https://github.com/apache/maven/blob/main/api/maven-api-annotations/src/main/java/org/apache/maven/api/annotations/Component.java).

- **maven-api-model**: Provides immutable POJOs representing the `<project>` POM structure, including dependencies, plugins, and build configurations. The entry point is `org.apache.maven.api.model.Model` in [`api/maven-api-model/src/main/java/org/apache/maven/api/model/Model.java`](https://github.com/apache/maven/blob/main/api/maven-api-model/src/main/java/org/apache/maven/api/model/Model.java).

- **maven-api-settings**: Defines objects for `<settings.xml>` parsing, encapsulating servers, proxies, and mirrors. Key class: `org.apache.maven.api.settings.Settings` at [`api/maven-api-settings/src/main/java/org/apache/maven/api/settings/Settings.java`](https://github.com/apache/maven/blob/main/api/maven-api-settings/src/main/java/org/apache/maven/api/settings/Settings.java).

- **maven-api-toolchain**: Abstracts toolchain definitions (JDK versions, compilers) used during the build. Interface located at [`api/maven-api-toolchain/src/main/java/org/apache/maven/api/toolchain/Toolchain.java`](https://github.com/apache/maven/blob/main/api/maven-api-toolchain/src/main/java/org/apache/maven/api/toolchain/Toolchain.java).

### Execution and Plugin APIs

- **maven-api-plugin**: Describes plugin descriptors including goals, parameters, and lifecycle bindings. The `PluginDescriptor` class resides in [`api/maven-api-plugin/src/main/java/org/apache/maven/api/plugin/descriptor/PluginDescriptor.java`](https://github.com/apache/maven/blob/main/api/maven-api-plugin/src/main/java/org/apache/maven/api/plugin/descriptor/PluginDescriptor.java).

- **maven-api-cli**: Exposes the public command-line interface façade through `org.apache.maven.api.cli.MavenCli`, enabling programmatic embedding of Maven execution.

- **maven-api-core**: Provides shared core services including XML factories, version handling, and request tracing. Contains `org.apache.maven.api.services.xml.XmlFactory` in [`api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java`](https://github.com/apache/maven/blob/main/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java).

### Infrastructure and Service Provider APIs

- **maven-api-xml**: Low-level DOM-style XML utilities for reading and writing. Primary interface: `org.apache.maven.api.xml.XmlService` at [`api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlService.java`](https://github.com/apache/maven/blob/main/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlService.java).

- **maven-api-di**: Minimal dependency-injection layer using annotations like `@Inject`, avoiding heavyweight frameworks such as Guice or Spring. Located in [`api/maven-api-di/src/main/java/org/apache/maven/api/di/Inject.java`](https://github.com/apache/maven/blob/main/api/maven-api-di/src/main/java/org/apache/maven/api/di/Inject.java).

- **maven-api-metadata**: Handles artifact metadata including checksums and signatures. Entry point: `org.apache.maven.api.metadata.Metadata` in [`api/maven-api-metadata/src/main/java/org/apache/maven/api/metadata/Metadata.java`](https://github.com/apache/maven/blob/main/api/maven-api-metadata/src/main/java/org/apache/maven/api/metadata/Metadata.java).

- **maven-api-spi**: Service-Provider-Interface definitions for extension points including `ModelParser` and `VersionResolver`. Key files include [`api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParser.java`](https://github.com/apache/maven/blob/main/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParser.java) and [`api/maven-api-spi/src/main/java/org/apache/maven/api/spi/VersionResolver.java`](https://github.com/apache/maven/blob/main/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/VersionResolver.java).

## Dependency Architecture and Binary Compatibility

The [`pom.xml`](https://github.com/apache/maven/blob/main/pom.xml) in the `api/` directory defines a strict dependency hierarchy: each module declares dependencies only on other API modules, never on implementation modules located in `impl/`. This guarantees that consuming a single artifact like `maven-api-model` does not transitively pull in the Maven runtime, XML parsers, or logging frameworks.

Binary compatibility across Maven 4 minor releases is enforced by the `japicmp-maven-plugin` configured in the parent POM. This ensures that public methods and classes remain stable, allowing tools compiled against Maven 4.0.0 to function correctly with Maven 4.9.9 without recompilation.

## Practical Implementation Patterns

### Parsing a POM via the SPI

To parse a POM file into a `Model` object, obtain the `ModelParser` service implementation and invoke the parse method:

```java
import org.apache.maven.api.model.Model;
import org.apache.maven.api.spi.ModelParser;
import java.nio.file.Path;
import java.nio.file.Paths;

Path pom = Paths.get("pom.xml");
ModelParser parser = lookup(ModelParser.class);  // SPI lookup via maven-api-di
Model model = parser.parse(pom, ModelParser.Mode.DEFAULT);

```

### Walking Dependency Trees

Once parsed, the `Model` provides immutable accessors for inspecting dependencies:

```java
model.getDependencies().stream()
    .filter(d -> "compile".equals(d.getScope()))
    .forEach(d -> System.out.println(
        d.getGroupId() + ":" + d.getArtifactId() + ":" + d.getVersion()
    ));

```

### Resolving Version Ranges

The `VersionResolver` SPI converts version ranges into concrete artifacts:

```java
import org.apache.maven.api.VersionRange;
import org.apache.maven.api.Version;
import org.apache.maven.api.spi.VersionRangeResolver;

VersionRangeResolver vrResolver = lookup(VersionRangeResolver.class);
VersionRange range = VersionRange.createFromString("[1.0,2.0)");
Version resolved = vrResolver.resolve(range, repositorySystemSession);

```

### Generating XML Fragments

Use `XmlService` for lightweight XML manipulation without external libraries:

```java
import org.apache.maven.api.xml.XmlService;
import org.apache.maven.api.xml.XmlNode;

XmlService xml = lookup(XmlService.class);
XmlNode node = xml.createElement("message")
                  .addContent(xml.createText("Hello Maven API"));
System.out.println(node.toString());

```

### Embedding the Maven CLI

For tools requiring full build execution, embed the CLI programmatically:

```java
import org.apache.maven.api.cli.MavenCli;

MavenCli cli = new MavenCli();
int exitCode = cli.doMain(
    new String[] {"verify"}, 
    projectRoot.toString(), 
    System.out, 
    System.err
);

```

*Note: All `lookup()` calls resolve through Maven's lightweight DI container defined in `maven-api-di`.*

## Summary

- **Maven 4's API modules** reside under `api/` and provide stable contracts for tool development without runtime dependencies.
- **Eleven modules** cover annotations, models, settings, toolchains, plugins, XML, DI, metadata, SPI, CLI, and core services.
- **Strict dependency rules** prevent API modules from referencing implementation code, ensuring lightweight consumption.
- **Binary compatibility** is enforced via `japicmp-maven-plugin` across minor releases.
- **SPI patterns** allow developers to parse POMs, resolve versions, and execute builds through clean interfaces like `ModelParser` and `MavenCli`.

## Frequently Asked Questions

### What is the difference between Maven API modules and implementation modules?

**API modules** (located in `api/`) contain only interfaces, annotations, and POJOs that define contracts, while **implementation modules** (located in `impl/`) provide the concrete logic for parsing, resolving, and executing builds. Developers should compile against API modules to avoid coupling their code to internal implementation details that may change between releases.

### How do I add Maven API modules to my project?

Add the specific API artifact to your Maven dependencies using the coordinates `org.apache.maven:maven-api-<module>:<version>`, for example:

```xml
<dependency>
    <groupId>org.apache.maven</groupId>
    <artifactId>maven-api-model</artifactId>
    <version>4.0.0</version>
</dependency>

```

All API modules share the same version number as the Maven release, defined by `${project.version}` in the parent POM.

### Are Maven API modules backward compatible?

Yes, Maven 4 API modules maintain **binary compatibility** across minor releases. The `japicmp-maven-plugin` configuration in the parent [`pom.xml`](https://github.com/apache/maven/blob/main/pom.xml) enforces this by comparing current artifacts against baselines, ensuring that public methods and classes remain unchanged or only extended in backward-compatible ways.

### Can I implement custom SPIs for Maven?

**Absolutely.** The `maven-api-spi` module defines extension points such as `ModelParser`, `VersionResolver`, and transport layers. By implementing these interfaces and registering them through Maven's DI system (using annotations from `maven-api-di`), you can override default behaviors for POM parsing, version resolution, or artifact transport without modifying Maven's core implementation.