Migrate from v1 to v2
How to migrate from the v1 SDK to the v2 SDK.
The Java v1 SDK will be deprecated on 1 January 2024.
This guide covers two ways to migrate from v1 to v2 of the Java SDK:
Example code in this migration guide uses placeholders that should be replaced with the following values:
|project_key||your API Client|
|client_id||your API Client|
|secret||your API Client|
|scope||your API Client|
Manually migrate to v2 SDK
The following example code demonstrates how to perform an action using the Java v1 SDK, and the best practice for replicating this action with the Java v2 SDK.
Client configuration and creation
SphereClientFactory has been replaced by
The benefit is that after the
ApiRoot has been instantiated, requests can be created directly from it.
Both SDKs use the method
executeBlocking() to set the timeout.
To set headers, in the v1 SDK there is the
HttpRequest class and in the v2 SDK the
The main difference, as you can see in the example below, is that the
ApiHttpRequest can be directly instantiated and it can set the type of method (GET or POST), the URI, the headers, and the body.
In the examples below there is a significant difference in the retry mechanisms between the v1 SDK and the v2 SDK.
In the v1 SDK, the retry mechanism has to be defined piece by piece: first the retry rules, then the
SphereClient, and then the request, in this case, a
In the v2 SDK, the setup of the request can be built directly during the client creation.
ByProjectKeyRequestBuilder can be created with a built-in retry mechanism using the
RetryMiddleware. It is also possible to set up additional parameters to the request, like the logger
In the v2 SDK there are not inheritances for DraftBuilder classes, but the differences are minor.
In the v2 SDK there are no dedicated classes for the create command, but there are builders instead. The Create Command needs a Draft that is built and passed to the
Create resources from JSON
In the v2 SDK, the
JsonUtils class replaces the
In the v2 SDK there are no dedicated classes for the update command. The
UpdateBuilder is used to create the type of update action to apply in the
Get a resource by ID
Retrieving resources by ID in the v2 SDK requires
.get(), after which additional filters or requests (such as
.withExpand()) can be included before the request is executed.
To build complex queries, the v2 SDK uses
ResourcePagedQueryResponse (as opposed to
PagedQueryResult in the v1 SDK).
ResourcePagedQueryResponse can apply the limit, count, total, offset, and result to the query.
Compatibility layer for Java v1 SDK
The Java v2 SDK introduced breaking changes to the SDK client configuration. The commercetools-sdk-compat-v1 compatibility layer module allows you to use the v2 SDK in conjunction with the v1 SDK, enabling you to simplify the migration process.
When you use the compatibility layer, the v1 SDK adapts its internal logic, so you don't need to change your whole business logic. Use this flexibility to gradually migrate to the v2 SDK.