Get started with the Java SDK

Learn how to set up and use the Java SDK.

This step-by-step guide leads you through setting up and making API calls using the Java SDK.

Requirements

To follow this guide you should have the following:

A commercetools Composable Commerce Project
An API Client
Java 8 (or later)

For more information on setting up a commercetools Composable Commerce Project or API Client, follow our Getting started with commercetools Composable Commerce guides.

Objectives of the get started guide

After following this guide you will have:

Installed the Java SDK
Created a Client class
Tested your Client
Learned how to make API calls with the Java SDK

Placeholder values

Example code in this guide uses placeholders that should be replaced with the following values.

If you do not have an API Client, follow our Get your API Client guide.

Placeholder	Replace with	From
`{projectKey}`	project_key	your API Client
`{clientID}`	client_id	your API Client
`{clientSecret}`	secret	your API Client
`{scope}`	scope	your API Client
`{region}`	your Region	Hosts

Install the Java SDK

Gradle

Add the following to your build.gradle file.

This has been configured to install the latest version of each dependency. To use a specific version, replace latest.release with the version number.

 ext {
     versions = [
         commercetools: "latest.release"
     ]
 }

 repositories {
     mavenCentral()
 }

 dependencies {
     implementation "com.commercetools.sdk:commercetools-http-client:${versions.commercetools}"
     implementation "com.commercetools.sdk:commercetools-sdk-java-api:${versions.commercetools}"
     implementation "com.commercetools.sdk:commercetools-sdk-java-importapi:${versions.commercetools}"
     implementation "com.commercetools.sdk:commercetools-sdk-java-history:${versions.commercetools}"
 }

Maven

Add the following to your pom.xml file.

This has been configured to install the latest version of each dependency. To use a specific version, replace LATEST with the version number.

 <properties>
     <commercetools.version>LATEST</commercetools.version>
 </properties>

 <dependencies>
     <dependency>
       <groupId>com.commercetools.sdk</groupId>
       <artifactId>commercetools-http-client</artifactId>
       <version>${commercetools.version}</version>
     </dependency>
     <dependency>
       <groupId>com.commercetools.sdk</groupId>
       <artifactId>commercetools-sdk-java-api</artifactId>
       <version>${commercetools.version}</version>
     </dependency>
     <dependency>
       <groupId>com.commercetools.sdk</groupId>
       <artifactId>commercetools-sdk-java-importapi</artifactId>
       <version>${commercetools.version}</version>
     </dependency>
     <dependency>
       <groupId>com.commercetools.sdk</groupId>
       <artifactId>commercetools-sdk-java-history</artifactId>
       <version>${commercetools.version}</version>
     </dependency>
 </dependencies>

Maven Central

A full list of commercetools SDKs and the latest versions can be found at Maven Central Repository Search.

For any of the SDK modules an HTTP client module must be installed. The default one is commercetools-http-client.

The commercetools-sdk-java-importapi (Import API) and commercetools-sdk-java-history (Change History API) are only needed for more specific use cases.

Troubleshooting with the Spring Framework

The Spring Framework has an optional dependency to OkHttp in version 3.x.

To avoid problems use the commercetools-okhttp-client3 or commercetools-apachehttp-client module instead of the module commercetools-http-client.

Create the Client class

Create a class called Client and add the following code:

// Add your package information here

// Required imports
import com.commercetools.api.client.ProjectApiRoot;
import com.commercetools.api.defaultconfig.ApiRootBuilder;
import com.commercetools.api.defaultconfig.ServiceRegion;
import io.vrap.rmf.base.client.oauth2.*;

public class Client {

  public static ProjectApiRoot createApiClient() {
        final ProjectApiRoot apiRoot = ApiRootBuilder.of()
        .defaultClient(ClientCredentials.of()
                .withClientId("{clientID}")
                .withClientSecret("{clientSecret}")
                .build(),
        ServiceRegion.YOUR_SERVICE_REGION)
        .build("{projectKey}");

        return apiRoot;
    }
}

ServiceRegion is an enum and you should use one of the following values based on where your commercetools Project is hosted:

ServiceRegion value	Region
`ServiceRegion.GCP_EUROPE_WEST1`	europe-west1.gcp
`ServiceRegion.GCP_US_CENTRAL1`	us-central1.gcp
`ServiceRegion.AWS_US_EAST_2`	us-east-2.aws
`ServiceRegion.AWS_EU_CENTRAL_1`	eu-central-1.aws
`ServiceRegion.GCP_AUSTRALIA_SOUTHEAST1`	australia-southeast1.gcp

Test the Client

In your Java program, add the following code:

// Required imports
import com.commercetools.api.client.ProjectApiRoot;
import com.commercetools.api.models.project.*;

// Create the apiRoot with your Client
ProjectApiRoot apiRoot = Client.createApiClient();

// Make a get call to the Project
Project myProject = apiRoot
  .get()
  .executeBlocking()
  .getBody();

// Output the Project name
System.out.println(myProject.getName());

apiRoot can now be used to build requests to the Composable Commerce API.

This code includes an example API call that gets your Project to the myProject object and outputs the Project's name using .getName().

Using the Java SDK

Imports

Without importing resource-specific packages and interfaces you will be unable to use/access specific objects and methods.

For example, to use or create a Shopping List you must import:

import com.commercetools.api.models.shopping_list.ShoppingList;
import com.commercetools.api.models.shopping_list.ShoppingListDraft;

Alternatively, you can include everything from the com.commercetools.api.models.shopping_list package using:

import com.commercetools.api.models.shopping_list.*;

A list of the available packages to import can be found in the Javadoc.

Using builders

The Java SDK follows a builder pattern when constructing drafts, update actions, and other objects/types that contain multiple fields.

// Create a LocalizedString
LocalizedString multiLanguageString = LocalizedString
  .builder()
  .addValue("en", "English value")
  .addValue("de", "German value")
  .build();

// Create US$100.00
Money money = Money.builder().currencyCode("USD").centAmount(10000l).build();

// Create a Category
CategoryDraft categoryDraft = CategoryDraft
  .builder()
  .name(LocalizedString.ofEnglish("english name"))
  .slug(stringBuilder -> stringBuilder.addValue("en", "english-slug"))
  .key("category-key")
  .build();

Consult the HTTP API reference to ensure that all required fields are included.

Once the fields/values are added, .build() finishes building the object.

How to structure your API call

Calls to the Java SDK require you to make an instance of the type you want returned, or an instance of an action to take:

// Return the information of a specific Shopping List
ShoppingList shoppingListInfo
// ...

// Return all Shopping Lists
ShoppingListPagedQueryResponse allShoppingLists
// ...

// Create an update action for setting a Shopping List key
ShoppingListSetKeyAction shoppingListSetKeyAction
// ...

Retrieving data

When retrieving, include the apiRoot and the associated endpoint.

// Get information of a specific Shopping List
ShoppingList shoppingListInfo = apiRoot
.shoppingLists()
// ...

// Return all Shopping Lists
ShoppingListPagedQueryResponse allShoppingLists = apiRoot
.shoppingLists()
// ...

Get a single resource

When getting a specific resource, you should include its ID or key followed by .get(), .executeBlocking() and .getBody();.

// Information of a specific Shopping List by ID
ShoppingList shoppingListInfo = apiRoot
  .shoppingLists()
  .withId("{shoppingListID}")
  .get()
  .executeBlocking()
  .getBody();

// Information of a specific Shopping List by key
ShoppingList shoppingListInfo = apiRoot
  .shoppingLists()
  .withKey("{shoppingListKey}")
  .get()
  .executeBlocking()
  .getBody();

The shoppingListInfo object would then contain all the data of the specified Shopping List. Individual information can be accessed from the fields within that object:

Get multiple resources

When returning a list of resources, a PagedQueryResponse should be used based on the resource you want to return. For example, a ShoppingListPagedQueryResponse returns Shopping Lists.

PagedQueryResponse is identical to PagedQueryResult in the HTTP API.

// Return all Shopping Lists in a PagedQueryResponse
ShoppingListPagedQueryResponse allShoppingLists = apiRoot
  .shoppingLists()
  .get()
  .executeBlocking()
  .getBody();

The results of these calls can be altered by including .withWhere(), .withSort(), .withExpand(), .withLimit(), or .withOffset() after .get().

These are identical to the parameters you can add to standard HTTP API calls. If your IDE supports autocomplete you can view a full list of methods available:

Using the Query Predicate builder

For querying results you can also use the type safe Query Predicate builders. They allow you to programmatically create a Query Predicate using the withQuery method.

// Return all Customers that have not verified their email address
final CustomerPagedQueryResponse response = apiRoot
  .customers()
  .get()
  .withQuery(c -> c.isEmailVerified().is(false))
  .executeBlocking()
  .getBody();

Viewing results

A list of resources within a PagedQueryResponse can be accessed using .getResults():

// Return all Shopping Lists
ShoppingListPagedQueryResponse allShoppingLists = apiRoot
  .shoppingLists()
  .get()
  .executeBlocking()
  .getBody();

// Put the returned Shopping Lists in a new list
List<ShoppingList> listOfShoppingLists = allShoppingLists.getResults();

// Create a String containing the first Shopping List's English name
String firstShoppingListName = listOfShoppingLists.get(0).getName().get("en");

Writing a resource

When writing to a resource, include the apiRoot and the associated endpoint.

// Create a Shopping List
ShoppingList newShoppingList = apiRoot
.shoppingLists()
// ...

// Update a Shopping List
ShoppingList updatedShoppingList = apiRoot
.shoppingLists()
// ...

Creating a new resource

Creating a new resource requires a draft of the resource to create. For Shopping Lists this would be a ShoppingListDraft. These drafts are created using builders:

// Create ShoppingListDraft with required fields
ShoppingListDraft newShoppingListDraft = ShoppingListDraft
  .builder()
  .name(
    LocalizedString
      .builder()
      .addValue("en", "English name of Shopping List")
      .build()
  )
  .build();

This draft should be included within post() followed by .executeBlocking() and .getBody().

// Create a Shopping List
ShoppingList newShoppingList = apiRoot
  .shoppingLists()
  .post(newShoppingListDraft)
  .executeBlocking()
  .getBody();

Updating an existing resource

Updating an existing resource requires a .withId() or .withKey() that references a unique identifier of the resource.

// Update a Shopping List
ShoppingList updatedShoppingList = apiRoot
  .shoppingLists()
  .withId("{shoppingListID}")
  // ...

When posting to a specific resource, a payload must be included. This payload (in the case of Shopping Lists, a ShoppingListUpdate) contains an array of update actions and the last seen version of the resource.

Update actions and payloads are created using builders.

// Create the payload - a ShoppingListUpdate - with the current version of the Shopping List and the update actions.
ShoppingListUpdate shoppingListUpdate = ShoppingListUpdateBuilder
  .of()
  .version(1L)
  .plusActions(actionBuilder ->
    actionBuilder.setKeyBuilder().key("a-unique-shoppinglist-key")
  )
  .build();

The payload must then be passed as an argument to the .post() method.

// Update a Shopping List
ShoppingList updatedShoppingList = apiRoot
  .shoppingLists()
  .withId("{shoppingListID}")
  .post(shoppingListUpdate)
  .executeBlocking()
  .getBody();

Deleting a resource

Deleting a resource requires using the .delete() method with the last seen version of the resource. The resource to delete must be identified using withId() or withKey().

// Delete and return a Shopping List
ShoppingList deletedShoppingList = apiRoot
  .shoppingLists()
  .withId("{shoppingListID}")
  .delete()
  .withVersion(1l)
  .withDataErasure(true) // Include to erase related personal data
  .executeBlocking()
  .getBody();

Retrieving the raw API response

The above examples use .executeBlocking() to return the resource as an instance of an object.

To return the response as a byte array instead, use .sendBlocking(). Note that with this approach you must create a byte array as the value to return:

// Return a ShoppingListPagedQueryResponse as a byte array
byte[] shoppingLists = apiRoot.shoppingLists().get().sendBlocking().getBody();

// Convert to a String and output to the console
String shoppingListDetails = new String(
  shoppingLists,
  java.nio.charset.StandardCharsets.UTF_8
);
System.out.println(shoppingListDetails);

Using GraphQL

The Java SDK has a GraphQL module that provides type safe GraphQL support.

With the help of the DGS codegen you can generate a type safe query and projection builder. The results are then mapped to the correct response type.

The response types have all available fields, but only the projected will contain a value.

final GraphQLRequest<ProductQueryResult> productQuery = GraphQL
  .products(query -> query.localeProjection(Collections.singletonList("en")))
  .projection(root ->
    root.results().id().key().productType().key().getParent().createdAt()
  );

final ApiHttpResponse<GraphQLResponse<ProductQueryResult>> response =
  projectRoot.graphql().query(productQuery).executeBlocking();

final ProductQueryResult data = response.getBody().getData();

Using non-blocking calls

The Java SDK also allows non-blocking calls which return a CompletableFuture.

To return the resource as an instance of an object use .execute(). To return a byte array use .send():

// Return all Shopping Lists using a CompletableFuture - execute()
apiRoot
  .shoppingLists()
  .get()
  .execute()
  .thenAccept(response -> {
    ShoppingListPagedQueryResponse allShoppingLists = response.getBody();
    // Assign the first Shopping List's ID to a string and output it to the console
    String firstshoppingListID = allShoppingLists.getResults().get(0).getId();
    System.out.println(firstshoppingListID);
  })
  .join();

// Return all Shopping Lists in a byte array using a CompletableFuture - send()
apiRoot
  .shoppingLists()
  .get()
  .send()
  .thenAccept(response -> {
    byte[] shoppingLists = response.getBody();
    // Convert to a String and output to the console
    String shoppingListDetails = new String(
      shoppingLists,
      java.nio.charset.StandardCharsets.UTF_8
    );
    System.out.println(shoppingListDetails);
  })
  .join();

Next steps

Try our example code

Continue learning about the Java SDK by checking our SDK code examples. You will find example code for creating, querying, and updating Customers and Products.

Set up a demo application

The Me Endpoint Checkout app demonstrates how to use the Me endpoints to create an example web store.