Automate your SP-API calls using Java SDK

by Supriya P., Solutions Architect, Selling Partner Developer Services | April 25, 2022

If you are a developer who just started calling SP-APIs, you can automate the process with a Java Software Development Kit (SDK). An SDK bundles multiple steps together, such as requesting an access token, requesting a security token, and signing requests with Signature Version 4 (SigV4), to call the SP-APIs seamlessly. This post provides you with all the required details to generate a Java SDK with Login with Amazon (LWA) token exchange and authentication to build your application seamlessly. You learn the prerequisites required to build the Java SDK and also see an example using the Selling Partner API for Sellers and Swagger Code Generator.

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

How does authorization automation work?

The authorization for Selling Partner API is based on Login with Amazon (LWA). Login with Amazon helps you protect your customer information by leveraging the Amazon.com user authentication system. Login with Amazon is based on OAuth 2.0. (For more information on Login with Amazon, refer to Login with Amazon Documentation.)

At a high level, the Login with Amazon process is as follows:

1. The seller accepts your application.
2. Amazon calls your callback URL with an authorization code.
3. You trade this authorization code with a long term refresh token that you can store.
4. When you want to make SP-API calls, you use this refresh token to get an access token that is valid for one hour.

To access SP-APIs, an LWA refresh token is exchanged for an LWA access token. An access token obtained through this token exchange must be included in the header for each API call, except for restricted operations and grantless operations. After an access token is issued, it is only valid for one hour. The same access token can be used for multiple API calls until it expires, then you need to request another token. With a Java SDK, you can automate this entire process!

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
• IDE software (this walkthrough uses Eclipse IDE on Windows OS)

If you do not have a hybrid or SP-API app, follow the steps to register as a developer and register your application in the Selling Partner API Developer Guide. Then, return to this blog post.

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.

1. On your local drive, create a directory for this project and name it SwaggerToCL.
2. Download the following tools and and make them available in your $PATH.
   • Java 8 or newer
   • Apache Maven 3.6 or greater
   • GNU Wget
3. 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

4. Copy swagger-codegen-cli.jar into your local directory C:\SwaggerToCL.
5. 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

6. Navigate to the selling-partner-api-models\models folder in your local copy of the repository and copy each JSON file 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: You may notice that developers can 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, see 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 selling-partner-api-models\clients\sellingpartner-api-aa-java folder of your local copy of the repository. This folder contains an authorization and authentication library, along with customized templates for the Swagger Code Generator.

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] 

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 

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

The generated SDK has the classes for configuring your LWA and AWS credentials and uses these to exchange LWA tokens and sign requests for you.

Step 3. Build the AA library

After you generate the SDK, build the AA library.

1. 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-1.0-jar-with-dependencies.jar (or similarly named) and all of the required dependencies.
2. 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=1.0 -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-1.0.jar -DgroupId=com.amazon.sellingpartnerapi -DartifactId=sellingpartnerapi-aa-java -Dversion=1.0 -Dpackaging=jar

mvn install:install-file -Dfile=C:\SwaggerToCL\sellingpartner-api-aa-java\target\sellingpartnerapi-aa-java-1.0-jar-with-dependencies.jar -DgroupId=com.amazon.sellingpartnerapi -DartifactId=sellingpartnerapi-aa-java -Dversion=1.0 -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.

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

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

3. 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.

1. In Eclipse IDE, on the File menu, choose Open Projects from File System and then import the generated Java SDK.

2. In src/main/java add a class to write your code.

3. Write code in the added class to configure each of the following instances:

   • AWS credentials (see Configure your AWS credentials)
   • AWS credentials provider (see Configure your AWS credentials provider)
   • LWA credentials (see 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.

4. Create an instance of the generated SDK API and call the operations. For an example, see the following sample code for connecting to the Selling Partner API for Sellers (provided that you generated the JDK 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.AWSAuthenticationCredentials;
import com.amazon.SellingPartnerAPIAA.AWSAuthenticationCredentialsProvider;
import com.amazon.SellingPartnerAPIAA.LWAAuthorizationCredentials;
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 AWS credentials :
        AWSAuthenticationCredentials awsAuthenticationCredentials=AWSAuthenticationCredentials.builder()
                  .accessKeyId("*********************")
                  .secretKey("***********************")
                  .region("us-east-1")
                  .build();
       
        //Configure your AWS credentials provider :
        AWSAuthenticationCredentialsProvider awsAuthenticationCredentialsProvider=AWSAuthenticationCredentialsProvider.builder()
                  .roleArn("arn:aws:iam::************:role/SellingPartner")
                  .roleSessionName("postmanSpApi")
                  .build();
        
        //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()
                  .awsAuthenticationCredentials(awsAuthenticationCredentials)
                  .lwaAuthorizationCredentials(lwaAuthorizationCredentials)
                  .awsAuthenticationCredentialsProvider(awsAuthenticationCredentialsProvider)
                  .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();
        }
    }
 }

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. Happy coding!

Conclusion

In this blog, 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. For more information about this process, see Generate a Java SDK with LWA token exchange and authentication in the Developer Guide.

👍

Have feedback on this post?

If you have questions or feedback on this post, we'd like to hear from you! Please vote and leave a comment using the tools at the bottom of this page.

Subscribe to updates via RSS feed.