Skip to content

Add modular API family artifacts #2027

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
araiprof wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add modular API family artifacts #2027

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,51 @@ You can use Maven and add this dependency to your project's POM:

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-java-api-library/releases).

### Modular artifacts

The default artifact contains every API, model, webhook, and Terminal API class. Applications that
only use part of the library can instead depend on the `core` classifier and one or more API-family
classifiers:

| Classifier | Contents |
|---|---|
| `core` | Client, HTTP transport, shared request and error models, serializers, and utilities |
| `checkout` | Checkout API and models |
| `platforms` | Balance Platform, Balance Control, Capital, Legal Entity Management, Management, Session Authentication, and Transfers APIs and models |
| `payments` | Bin Lookup, Data Protection, Disputes, Open Banking, Payments, Payouts, Recurring, and Stored Value APIs and models |
| `terminal` | Terminal API, Cloud Device, Mobile, Payments App, and Terminal Fleet Management classes and models |
| `classic-platforms` | Classic Platforms APIs and models |
| `webhooks` | Webhook models and HMAC validation |
| `webhook-handlers` | Convenience webhook handlers; also requires `webhooks`, `payments`, and `terminal` |

Every API-family classifier requires `core`. For example, a Maven application that only uses the
Checkout API can use:

```xml
<dependency>
<groupId>com.adyen</groupId>
<artifactId>adyen-java-api-library</artifactId>
<version>43.0.0</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>com.adyen</groupId>
<artifactId>adyen-java-api-library</artifactId>
<version>43.0.0</version>
<classifier>checkout</classifier>
</dependency>
```

The equivalent Gradle dependencies are:

```groovy
implementation("com.adyen:adyen-java-api-library:43.0.0:core")
implementation("com.adyen:adyen-java-api-library:43.0.0:checkout")
```

The unclassified artifact remains available and unchanged for applications that prefer a single
dependency or need the complete library.

## Using the library

### General use with API key
Expand Down
201 changes: 201 additions & 0 deletions pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,207 @@
<manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile>
</archive>
</configuration>
<executions>
<execution>
<id>core-jar</id>
<phase>package</phase>
<goals>
<goal>jar</goal>
</goals>
<configuration>
<classifier>core</classifier>
Comment on lines +90 to +98

@gemini-code-assist gemini-code-assist Bot Aug 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

While using Maven classifiers to partition a single JAR is a clever way to avoid restructuring the source code, it introduces several significant limitations that impact developer experience and dependency management:

  1. No Transitive Dependency Reduction: Since all classifiers share the same pom.xml, a consumer depending on a lightweight classifier (like webhooks) will still transitively inherit all dependencies of the entire library (such as httpclient5, commons-codec, etc.). This defeats a key benefit of modularization (reducing classpath pollution and dependency conflicts).
  2. Missing Classified Sources and Javadocs: Currently, maven-source-plugin and maven-javadoc-plugin only build the default, unclassified sources/javadocs. When developers use a classifier like checkout, their IDEs (IntelliJ/Eclipse) will attempt to download adyen-java-api-library-43.0.0-checkout-sources.jar and fail, leaving them without source code navigation or Javadoc tooltips.
  3. Manual Dependency Management: Consumers must manually declare both core and the specific family classifier (e.g., checkout), which is verbose and error-prone.

Recommendation

The ideal solution is to transition to a standard Maven multi-module project (e.g., submodules for core, checkout, etc.).

If that is out of scope for this PR, you should at least configure the maven-source-plugin and maven-javadoc-plugin to generate matching classified JARs for each execution so that IDE integration is not broken.

<includes>
<include>com/adyen/*.class</include>
<include>com/adyen/constants/**</include>
<include>com/adyen/enums/**</include>
<include>com/adyen/httpclient/**</include>
<include>com/adyen/model/*.class</include>
<include>com/adyen/model/checkout/JSON*.class</include>
<include>com/adyen/serializer/**</include>
<include>com/adyen/service/exception/**</include>
<include>com/adyen/service/resource/*.class</include>
<include>com/adyen/util/*.class</include>
</includes>
<excludes>
<exclude>com/adyen/httpclient/TerminalLocalAPIHostnameVerifier.class</exclude>
<exclude>com/adyen/serializer/SaleToAcquirerDataSerializer.class</exclude>
<exclude>com/adyen/util/HMACValidator.class</exclude>
</excludes>
</configuration>
</execution>
<execution>
<id>checkout-jar</id>
<phase>package</phase>
<goals>
<goal>jar</goal>
</goals>
<configuration>
<classifier>checkout</classifier>
<includes>
<include>com/adyen/model/checkout/**</include>
<include>com/adyen/model/checkoututility/**</include>
<include>com/adyen/service/checkout/**</include>
</includes>
<excludes>
<exclude>com/adyen/model/checkout/JSON*.class</exclude>
</excludes>
</configuration>
</execution>
<execution>
<id>platforms-jar</id>
<phase>package</phase>
<goals>
<goal>jar</goal>
</goals>
<configuration>
<classifier>platforms</classifier>
<includes>
<include>com/adyen/model/balancecontrol/**</include>
<include>com/adyen/model/balanceplatform/**</include>
<include>com/adyen/model/capital/**</include>
<include>com/adyen/model/legalentitymanagement/**</include>
<include>com/adyen/model/management/**</include>
<include>com/adyen/model/sessionauthentication/**</include>
<include>com/adyen/model/transfers/**</include>
<include>com/adyen/service/BalanceControlApi*.class</include>
<include>com/adyen/service/balancecontrol/**</include>
<include>com/adyen/service/balanceplatform/**</include>
<include>com/adyen/service/capital/**</include>
<include>com/adyen/service/legalentitymanagement/**</include>
<include>com/adyen/service/management/**</include>
<include>com/adyen/service/sessionauthentication/**</include>
<include>com/adyen/service/transfers/**</include>
</includes>
</configuration>
</execution>
<execution>
<id>payments-jar</id>
<phase>package</phase>
<goals>
<goal>jar</goal>
</goals>
<configuration>
<classifier>payments</classifier>
<includes>
<include>com/adyen/model/additionalData/**</include>
<include>com/adyen/model/binlookup/**</include>
<include>com/adyen/model/dataprotection/**</include>
<include>com/adyen/model/disputes/**</include>
<include>com/adyen/model/openbanking/**</include>
<include>com/adyen/model/payment/**</include>
<include>com/adyen/model/payout/**</include>
<include>com/adyen/model/recurring/**</include>
<include>com/adyen/model/storedvalue/**</include>
<include>com/adyen/service/BinLookupApi*.class</include>
<include>com/adyen/service/DataProtectionApi*.class</include>
<include>com/adyen/service/DisputesApi*.class</include>
<include>com/adyen/service/PaymentApi*.class</include>
<include>com/adyen/service/RecurringApi*.class</include>
<include>com/adyen/service/StoredValueApi*.class</include>
<include>com/adyen/service/binlookup/**</include>
<include>com/adyen/service/dataprotection/**</include>
<include>com/adyen/service/disputes/**</include>
<include>com/adyen/service/openbanking/**</include>
<include>com/adyen/service/payment/**</include>
<include>com/adyen/service/payout/**</include>
<include>com/adyen/service/recurring/**</include>
<include>com/adyen/service/storedvalue/**</include>
</includes>
</configuration>
</execution>
<execution>
<id>terminal-jar</id>
<phase>package</phase>
<goals>
<goal>jar</goal>
</goals>
<configuration>
<classifier>terminal</classifier>
<includes>
<include>com/adyen/builders/**</include>
<include>com/adyen/httpclient/TerminalLocalAPIHostnameVerifier.class</include>
<include>com/adyen/model/applicationinfo/**</include>
<include>com/adyen/model/clouddevice/**</include>
<include>com/adyen/model/nexo/**</include>
<include>com/adyen/model/paymentsapp/**</include>
<include>com/adyen/model/posmobile/**</include>
<include>com/adyen/model/posterminalmanagement/**</include>
<include>com/adyen/model/tapi/**</include>
<include>com/adyen/model/terminal/**</include>
<include>com/adyen/security/**</include>
<include>com/adyen/serializer/SaleToAcquirerDataSerializer.class</include>
<include>com/adyen/service/PaymentsAppApi*.class</include>
<include>com/adyen/service/PosMobileApi*.class</include>
<include>com/adyen/service/PosPayment*.class</include>
<include>com/adyen/service/PosTerminalManagementApi*.class</include>
<include>com/adyen/service/TerminalCloudAPI*.class</include>
<include>com/adyen/service/TerminalLocalAPI*.class</include>
<include>com/adyen/service/clouddevice/**</include>
<include>com/adyen/service/paymentsapp/**</include>
<include>com/adyen/service/posmobile/**</include>
<include>com/adyen/service/resource/terminal/**</include>
<include>com/adyen/terminal/**</include>
<include>com/adyen/util/tapi/**</include>
</includes>
</configuration>
</execution>
<execution>
<id>classic-platforms-jar</id>
<phase>package</phase>
<goals>
<goal>jar</goal>
</goals>
<configuration>
<classifier>classic-platforms</classifier>
<includes>
<include>com/adyen/model/marketpayaccount/**</include>
<include>com/adyen/model/marketpayconfiguration/**</include>
<include>com/adyen/model/marketpayfund/**</include>
<include>com/adyen/model/marketpayhop/**</include>
<include>com/adyen/service/classicplatforms/**</include>
</includes>
</configuration>
</execution>
<execution>
<id>webhooks-jar</id>
<phase>package</phase>
<goals>
<goal>jar</goal>
</goals>
<configuration>
<classifier>webhooks</classifier>
<includes>
<include>com/adyen/model/acswebhooks/**</include>
<include>com/adyen/model/balancewebhooks/**</include>
<include>com/adyen/model/configurationwebhooks/**</include>
<include>com/adyen/model/disputewebhooks/**</include>
<include>com/adyen/model/managementwebhooks/**</include>
<include>com/adyen/model/marketpaywebhooks/**</include>
<include>com/adyen/model/negativebalancewarningwebhooks/**</include>
<include>com/adyen/model/notification/**</include>
<include>com/adyen/model/relayedauthorizationwebhooks/**</include>
<include>com/adyen/model/reportwebhooks/**</include>
<include>com/adyen/model/tokenizationwebhooks/**</include>
<include>com/adyen/model/transactionwebhooks/**</include>
<include>com/adyen/model/transferwebhooks/**</include>
<include>com/adyen/util/HMACValidator.class</include>
</includes>
</configuration>
</execution>
<execution>
<id>webhook-handlers-jar</id>
<phase>package</phase>
<goals>
<goal>jar</goal>
</goals>
<configuration>
<classifier>webhook-handlers</classifier>
<includes>
<include>com/adyen/notification/**</include>
</includes>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.jacoco</groupId>
Expand Down
Loading