Tutorial: Automate your SP-API calls using Java SDK

This tutorial describes how to generate a Java SDK with Login with Amazon (LWA) token exchange and authentication to build your application seamlessly. You will learn the prerequisites required to build the Java SDK and also view an example using the Selling Partner API for Sellers and Swagger Code Generator.

First, take a look at how the authorization process works.

Tutorial

The following tutorial will help you set up your own Java SDK for automating SP-API calls.

Prerequisites

To complete this tutorial, you need the following prerequisites:

A hybrid or SP-API app in draft or published state
Integrated development environment (IDE) software (this walkthrough uses Eclipse IDE on Windows OS)

Before your application can connect to the Selling Partner API, you must register it, and it must be authorized by a selling partner. If you do not have a hybrid or SP-API app, follow the steps to register as a developer, register your application, and Authorizing Selling Partner API applications. Then, return to this tutorial.

Next, set up your workspace for the tutorial.

Step 1. Set up your workspace

First, you’ll need to download the required software packages, download Swagger Code Generator, and clone the SP-API models repository.

On your local drive, create a directory for this project and name it SwaggerToCL.
Download the following tools and make them available in your $PATH.
Run the following command to download the Swagger Code Generator:

wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.13/swagger-codegen-cli-2.4.13.jar -O swagger-codegen-cli.jar

Copy swagger-codegen-cli.jar into your local directory C:\SwaggerToCL.
In GitHub, go to https://github.com/amzn/selling-partner-api-models/tree/main/models and use the following command to clone the selling-partner-api-models repository to your local directory C:\\SwaggerToCL.

git clone https://github.com/amzn/selling-partner-api-models

Navigate to the selling-partner-api-models\models folder in your local copy of the repository and copy all JSON files from the models subfolders into C:\\SwaggerToCL.

The selling-partner-api-models repository has two directories:

models directory - contains all the currently available Selling Partner API models.
Note: Developers use Swagger Codegen to generate client libraries from these models. Swagger CodeGen is an open source project which enables automatic generation of API client libraries (SDK generation), server stubs, and documentation from an OpenAPI specification. For more information, refer to Swagger Codegen.
clients directory - contains a Java library named sellingpartner-api-aa-java and a C# library named sellingpartner-api-aa-csharp with Mustache templates for use with swagger-codegen to generate client libraries with authentication and authorization functionality included. The sellingpartner-api-documents-helper-java folder contains helper classes for encrypted documents. The sample-code folder contains java code examples for the Restricted Data Token (RDT).

Now that you have completed the required setup, the next step is to generate the Java SDK with the authentication and authorization classes provided in the sellingpartner-api-aa-java folder.

Step 2. Generate Java SDK for SP-APIs

In this step, you generate the SDK against the templates in the folder selling-partner-api-models\clients\sellingpartner-api-aa-java in your local copy of the repository. This folder contains an authorization and authentication library, along with customized templates for the Swagger Code Generator, and a config file to generate the correct version of the SDK.

To generate the Java SDK, you need to run the following command for each JSON file in your local directory:

java -jar C:\SwaggerToCL\swagger-codegen-cli.jar generate \
-i C:\SwaggerToCL\[name of model].json \
-l java -t [path to selling-partner-api-models\clients\sellingpartner-api-aa-java folder]\resources\swagger-codegen\templates\ \
-o C:\SwaggerToCL\[name of client library] \
-c [path to selling-partner-api-models\clients\sellingpartner-api-aa-java folder]\resources\java\config.json

For example, run the following command to generate Java code for sellers.json.

java -jar C:\SwaggerToCL\swagger-codegen-cli.jar generate \
-i C:\SwaggerToCL\Sellers.json \
-l java -t [path to selling-partner-api-models\clients\sellingpartner-api-aa-java folder]\resources\swagger-codegen\templates\ \
-o C:\SwaggerToCL\Sellers_JavaCL \
-c [path to selling-partner-api-models\clients\sellingpartner-api-aa-java folder]\resources\java\config.json

Repeat this step to generate SDKs for each of the SP-APIs available in the models directory.

The generated SDK includes the classes for configuring your LWA credentials and uses them to exchange LWA tokens.

In the following steps, x.x refers to the latest version of the AA library. Refer to the readme to get the latest version.

Step 3. Build the Authentication/Authorization Library (AA) library

After you generate the SDK, build the AA library.

Navigate to the selling-partner-api-models\clients\sellingpartner-api-aa-java folder of your local copy of the repository and run mvn package. This generates a folder named target. In this folder is a JAR file named sellingpartnerapi-aa-java-x.x-jar-with-dependencies.jar (or similarly named) and all of the required dependencies.
Run the following command to install the JAR file in your local Maven repository.

mvn install:install-file -Dfile=[path to JAR file in "target" folder] -DgroupId=com.amazon.sellingpartnerapi -DartifactId=sellingpartnerapi-aa-java -Dversion=x.x -Dpackaging=jar

You can find the actual groupId, artifactId, and version values near the top of the pom.xml file in the selling-partner-api-models\clients\sellingpartner-api-aa-java folder.

Example:

mvn install:install-file -Dfile=C:\SwaggerToCL\sellingpartner-api-aa-java\target\sellingpartnerapi-aa-java-x.x.jar -DgroupId=com.amazon.sellingpartnerapi -DartifactId=sellingpartnerapi-aa-java -Dversion=x.x -Dpackaging=jar

mvn install:install-file -Dfile=C:\SwaggerToCL\sellingpartner-api-aa-java\target\sellingpartnerapi-aa-java-x.x-jar-with-dependencies.jar -DgroupId=com.amazon.sellingpartnerapi -DartifactId=sellingpartnerapi-aa-java -Dversion=x.x -Dpackaging=jar

Step 4. Add the library as a dependency of the SDK

To add the library as a dependency, you need to edit the pom.xml file.

In your local directory, navigate to selling-partner-api-models/clients/sellingpartner-api-aa-java and open the pom.xml file.
Add the following code as a dependency in the file.

<dependency>
  <groupId>com.amazon.sellingpartnerapi</groupId>
  <artifactId>sellingpartnerapi-aa-java</artifactId>
  <version>x.x</version>
</dependency>

Save and close the file.

The next step is to write the actual application and connect to the SP-API using the generated Java SDK.

Step 5. Connect to the Selling Partner API using the generated Java SDK

In this step, you connect to the Selling Partner API using your generated Java SDK. These steps use Eclipse IDE to import the generated SDK and connect to the Selling Partner API, but you can use your preferred IDE.

In Eclipse IDE, on the File menu, choose Open Projects from File System and then import the generated Java SDK.
In src/main/java add a class to write your code.
Enter code in the added class to configure the following instance:
- LWA credentials (refer to Configure your LWA credentials)
Note: If the class path doesn’t recognize the classes in Eclipse, you’ll need to add the JAR files that were created in the target folder, which is located in the generated SDK folder.
Create an instance of the generated SDK API and call the operations. For an example, refer to the following sample code for connecting to the Selling Partner API for Sellers (provided that you generated the SDK for this API).

import io.swagger.client.*;
import io.swagger.client.auth.*;
import io.swagger.client.model.*;
import io.swagger.client.api.SellersApi;
import java.io.File;
import java.util.*;
import com.amazon.SellingPartnerAPIAA.LWAAuthorizationCredentials;
import com.amazon.SellingPartnerAPIAA.LWAException;
import static com.amazon.SellingPartnerAPIAA.ScopeConstants.SCOPE_NOTIFICATIONS_API; // for grantless operations (Notifications API)
import static com.amazon.SellingPartnerAPIAA.ScopeConstants.SCOPE_MIGRATION_API; // for grantless operations (Authorization API)

public class SellersApiDemo {

    public static void main(String[] args) {

        //Configure your LWA credentials :
        LWAAuthorizationCredentials lwaAuthorizationCredentials = LWAAuthorizationCredentials.builder()
                  .clientId("amzn1.application-*********************")
                  .clientSecret("***********************************")
                  .refreshToken("Atzr|******************************")
                  .endpoint("https://api.amazon.com/auth/o2/token")
                  .build();

        //For Grantless operations (Authorization API and Notifications API), use following code :
                /* LWAAuthorizationCredentials lwaAuthorizationCredentials = LWAAuthorizationCredentials.builder()
                 .clientId("amzn1.application-*********************")
                 .clientSecret("***********************************")
                 .withScopes(SCOPE_NOTIFICATIONS_API, SCOPE_MIGRATION_API)
                 .endpoint("https://api.amazon.com/auth/o2/token")
                 .build(); */
        
        //Create an instance of the Sellers API and call an operation :
        SellersApi sellersApi = new SellersApi.Builder()
                  .lwaAuthorizationCredentials(lwaAuthorizationCredentials)
                  .endpoint("https://sellingpartnerapi-na.amazon.com") // use Sandbox URL here if you would like to test your applications without affecting production data.
                  .build();
        
        try {
            GetMarketplaceParticipationsResponse result = sellersApi.getMarketplaceParticipations();
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling SellersApi#getMarketplaceParticipations");
            e.printStackTrace();
        }
        catch (LWAException e) {
            System.err.println("LWA Exception when calling SellersApi#getMarketplaceParticipations");
            System.err.println(e.getErrorCode());
            System.err.println(e.getErrorMessage());
            e.printStackTrace();
        }
    }
 }

Now that you have run the code, run the main class and you should see a list of marketplaces that your authorized seller can sell in.

You can follow similar steps for other SP-APIs we provide.

Conclusion

In this tutorial, you learned how to automate your SP-API calls using a Java SDK. In the walkthrough, you learned how to set up your workspace, generate a Java SDK for Selling Partner API, connect to the Sellers API, and make the first API call.