AWS Marketplace
AWS Marketplace product management for sellers using Postman API Collections
AWS Marketplace is a digital store that makes it easy for customers to find, buy, deploy, and manage third-party software, data, and services on Amazon Web Services (AWS). As an independent software vendor (ISV) or developer, interacting with the AWS Marketplace APIs can streamline your processes. These include managing product listings, creating private offers, and handling customer agreements. Postman, a widely used API development platform, can make these interactions more seamless by providing an intuitive interface to send API requests and analyze responses. You can run entire collections of requests as automated sequences of API calls using Postman.
In this post, we will guide you through using preconfigured Postman collections to interact with the AWS Marketplace catalog. This is available on the official AWS Partners Postman API Network. We will cover setting up an AWS Signature authentication in Postman, configuring environment variables, and executing sample API requests using the following collections:
- AWS Marketplace Catalog API collections
- AWS Marketplace Labs by use cases:
- Create software as a service (SaaS) private offer
- Authorize SaaS reseller
The Postman collections for AWS Marketplace use cases include two labs. This blog post explores common AWS Marketplace Catalog API actions and demonstrates a use case for creating a software as a service (SaaS) private offer.
We’ll use Postman Vault, a feature that allows you to store sensitive information like AWS access keys as vault secrets on your local Postman instance. This enables secure reuse of confidential data in your HTTP collections and requests. Vault secrets are accessible only to you and aren’t synced with the Postman cloud, ensuring data privacy. By the end of this post, you’ll be equipped to efficiently use these collections to manage your AWS Marketplace interactions on the Postman platform.
Understanding AWS Marketplace APIs and Postman Collections
Using the AWS Marketplace Catalog API service, sellers can create, update, view, and filter products, offers, and resale authorizations programmatically.
The following Postman collections are available on the Postman API Network to interact with the following APIs:
- Catalog API collections – Contains requests for AWS Catalog API operations
- Create SaaS private offer – For creating SaaS private offers using an API
- Authorize SaaS reseller – For authorizing resellers using an API
Prerequisites
- AWS account – An active AWS account registered as a seller in AWS Marketplace.
- Product listing – A valid product listed in AWS Marketplace.
- AWS Identity and Access Management (IAM) role –
AWSMarketplaceSellerFullAccess. - AWS access keys – IAM user access key ID and secret access key.
- Postman – Install Postman on your machine or use the web version. Fork the AWS Marketplace API Collections to your own workspace.
To fork the AWS Marketplace API Collections, follow these steps :
- Navigate to AWS Marketplace Postman Workspace, in the navigation pane, select Collections.
- Next choose the collection you want to create a fork from(AWS Marketplace Catalog API).
- Click the three dots to expand the dropdown menu. Click Create a fork.
- Under Fork collection, for Fork label, enter a name for your label, such as “development fork.”
- For Workspace, put in “AWS Marketplace Private Workspace.”
- For Environments to fork, select 1 Environment from the drop down.
- Click on Fork Collection.
Figure 1 Create a fork from a collection
Setting up AWS Signature authentication in Postman
AWS Marketplace APIs use Signature Version 4 to securely authenticate API requests to AWS services. AWS Signature V4 (Sig V4) ensures that requests are coming from a verified source and prevents unauthorized access or tampering with the request during transit. Postman will be configured to handle AWS Signature authentication using Postman Vault and Postman environments.
Configure your Postman Vault
To configure your Postman Vault:
- In the Postman Workspace, at the bottom menu bar, click Vault.
- In the Postman Vault pane, enter your AWS secrets
-
- key: aws.accessKeyId; value: your AWS access key id value
- key: aws.secretAccessKey; value: your AWS secret access key
Figure 2 Configure credentials in postman vault
Configure your Postman environment
To configure your Postman environment:
- In the navigation pane on the left, click Environments. You will see three environments have been created for all the collections in the AWS Marketplace Workspace.
- Configure the values based on your use cases. Don’t change the endpoint values for aws.service and _.CAPI_PROD.
- To choose the right environment for the collection you want to work with, from the upper right corner under No environment, select the environment you just configured (i.e. Catalog API Environment).
Figure 3 Configure Postman Environment
Configure AWS signature authentication in collection and request
In the collection list pane, select the AWS Marketplace Catalog API collection
On the Authorization tab, for Auth Type, choose AWS Signature. Enter the appropriate values for AccessKey, SecretKey, AWS Region, and Service Name.
For each request, from the Authorization tab, under Auth Type, choose Inherit auth from parent.
Figure 4 Configure AWS Signature authentication
Configuring additional environment variables
Using the AWS Marketplace Catalog API Collection
The Catalog API Collection contains requests to interact with the AWS Marketplace Catalog API. Before running the Catalog API Collection, set up a few additional environmental variables. Make sure to add the variables under your Catalog API Environment, as shown in the Configure your Postman environment section.
- ListEntities action to provide list of AWS Marketplace catalog entities (products, offers, resale authorizations) from seller’s account.
- StartChangeSet action to request changes to seller’s catalog entities.
- DescribeChangeSet action to provide information about a given change set from seller’s account.
Example 1: Listing entities (ListEntities API)
-
- Navigate to Postman AWS Marketplace Catalog API collection
- Select DescribeAndList folder, navigate to the ListEntities request.
- Select Catalog API Environment from the Environment dropdown list.
- Confirm the method is POST and the URL is {{_.CAPI_PROD}}/ListEntities
- On the Body tab, select raw and JSON format
- Confirm the JSON payload is on the Body tab and click Send.
This example demonstrates the retrieval of 10 SaaS products from a seller account.{ "Catalog": "AWSMarketplace", "EntityType": "SaaSProduct", "MaxResults": 10 } - In the response, you can observe a list of SaaS entities.
{ "EntitySummaryList": [ { "AmiProductSummary": null, "ContainerProductSummary": null, "DataProductSummary": null, "EntityArn": "arn:aws:aws-marketplace:us-east-1:111111111111:AWSMarketplace/SaaSProduct/prod-1234567890", "EntityId": "prod-1234567890", "EntityType": "SaaSProduct", "LastModifiedDate": "2023-10-10T17:34:56Z", "Name": "Untitled - prod-1234567890", "OfferSummary": null, "ResaleAuthorizationSummary": null, "SaaSProductSummary": { "ProductTitle": null, "Visibility": "Draft" }, …… ], "NextToken": "Test_Token_rO0ABXVyABNbTGphdmEubGFuZy5PYmplY3Q7kM5YnxBzKWwCAAB4cAAAAAJzcgAOamF2YS5sYW5nLkxvbmc7i" } - To list more products, you can use pagination. To use pagination in Postman, add the following script in the Post-response area for the request and add NextToken in the request JSON payload.
var jsonData = pm.response.json(); if (jsonData.NextToken) { pm.collectionVariables.set("nextToken", jsonData.NextToken); } else { pm.collectionVariables.set("nextToken", null); } if ( pm.collectionVariables.get("nextToken")) { pm.execution.setNextRequest(pm.info.requestName); }Request json payload body:
{ "Catalog": "AWSMarketplace", "EntityType": "SaaSProduct" , "MaxResults": 10, "NextToken"：{{nextToken}} }The following screenshots show these scripts in the Postman Workspace.
Figure 5 ListEntities pagination Post-response script
Example 2: Create limited SaaS product and public offer with contract pricing
This example demonstrates how to programmatically create a SaaS product and public offer using the StartChangeSet API operation.
- Open the CreateLimitedSaasAndPublicOfferWithContractPricing request
- Make sure the request is Post request with the URL
{{ _.CAPI_PROD }}/StartChangeSet - The Body section contains a sample JSON payload to create a limited SaaS product.
Modify this payload as necessary for your specific requirements.{ "Catalog": "AWSMarketplace", "ChangeSet": [ { "ChangeType": "CreateProduct", "Entity": { "Type": "SaaSProduct@1.0" }, "ChangeName": "CreateProductChange", "DetailsDocument": {} }, { "ChangeType": "UpdateInformation", "Entity": { "Type": "SaaSProduct@1.0", "Identifier": "$CreateProductChange.Entity.Identifier" }, "DetailsDocument": { "ProductTitle": "Sample product", "ShortDescription": "Brief description", "LongDescription": "Detailed description", "Highlights": [ "Sample highlight" ], "SearchKeywords": [ "Sample keyword" ….. - Choose Send to submit the change set request.
- A successful API execution returns a response containing the ChangeSetId and ChangeSetArn.
{ "ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:111111111111:AWSMarketplace/ChangeSet/test_ChangeSetId", "ChangeSetId": "test_ChangeSetId " }
Example 3: Getting the details of a ChangeSet
The DescribeChangeSet API action retrieves detailed information about a specific change set. This change set is associated with the one created in the previous example.
- Navigate to the DescribeChangeSet in the Postman collection.
- In the Environment section, replace the placeholder ChangeSetId with your specific ChangeSetId.
- Open the DescribeChangeSet request.
- Set request type GET and URL to
{{ _.CAPI_PROD }}/DescribeChangeSet?catalog=AWSMarketplace&changeSetId={{ChangeSetId}} - Choose Send.
Figure 6 DescribeChangeSet API call - The response will show details of the change set along with the current status. In this instance, the status returned as “SUCCEEDED”.
Using the labs by use cases collections
The Labs by use cases collection includes practical examples for specific scenarios. The next section explores one use case, creating a SaaS private offer.
Creating a SaaS private offer
For more details about this use case, you can refer to the AWS Marketplace seller workshop
Create SaaS private offer with API.
For this lab, use the environment you configured for creating a SaaS private offer. The following screenshot illustrates the workflow for this process.
Figure 7 Create SaaS Private Offer Flow
There are two ways you can run this use case collection:
- To run each individual API request separately, select the request, then click Send. You can observe the response output in the response area, as shown in the following screenshot.
Figure 8 Run each API separately in the lab - To run the whole use case, select the three dots on the right side of the use case name.
Click Run folder.
Figure 9 Run whole lab by using Run folder - (Optional) You can configure different settings on the Functional tab. You can choose to run the collection manually or by scheduling it and you can select variables for the run configuration. Then click Run AWS Marketplace Labs by U…
Figure 10 Run folder configuration
You can observe the live responses from the API calls of each request on the Run results page.
Figure 11 Run folder response
Best practices and tips
- Use environment variables for each collection so you can reuse requests without hardcoding values.
- Use Postman’s Post-response scripts to store response values into environment variables or collection variables automatically.
Conclusion
This blog showed how Postman collections for AWS Marketplace API streamline API request management. They help make developing and testing AWS Marketplace API actions and use-cases more efficient.
By setting up AWS Signature authentication and configuring your environment variables, you can efficiently manage your AWS Marketplace entities and offers.
Whether you’re creating private offers or authorizing resellers, these collections provide a practical way to perform complex tasks with ease. As you become more familiar with the APIs and Postman, you’ll find new opportunities to automate and optimize your AWS Marketplace operations.
Additional Resources
- AWS Marketplace Seller Guide
- AWS Marketplace Catalog API Reference
- Authenticate with AWS Signature authentication workflow in Postman
- AWS seller workshops
- Store secrets in your Postman Vault
About the authors
Ming Zhu is a specialist solutions architect with AWS Marketplace. She focuses on supporting sellers to list their products in AWS Marketplace. Her responsibilities focus on automating and streamlining the AWS Partner onboarding experience. Besides work, her favorite things to do are swimming, traveling, and cooking.
Chandrashekar Vishweshwara is a specialist solutions architect with AWS Marketplace. He assists sellers in listing their products in AWS Marketplace. Beyond the office, he prioritizes family time and loves spending moments with his loved ones and loyal canine companion.