# Publishing a product in AWS Data Exchange containing APIs
The following topics describe the process of creating a REST API data set and publishing a new product that contains APIs on AWS Data Exchange. You can complete the process by using either the AWS Data Exchange console or the AWS Command Line Interface.
After you have set up your Amazon API Gateway REST API, you can create a new API data set in AWS Data Exchange. You can then create a revision, and add API assets.
Creating and publishing an API asset allows subscriber requests to an AWS Data Exchange endpoint to proxy through to your API Gateway API. You can then add this data set to a product and add pricing. Then, subscribers can view your product and subscribe to it in the AWS Marketplace catalog and the AWS Data Exchange catalog.
AWS Data Exchange features are available including revision access rules, private products, private offers, and subscription verification.
You can choose only contract-based pricing, metered cost pricing (where the contract pricing is \$10), or a combination of metered and contract pricing.
You can choose standard metered costs, or you can specify a custom metered cost. There are three types of standard metered costs available:
+ Per API request
+ Per successful API request
+ Per unit of data transferred in bytes
**Note**
Metered costs apply to all API data sets in a product. Therefore, if you want to charge different prices for the same dimension for different API data sets, we recommend that you create these data sets in different products.
The process has the following steps:
**Topics**
+ [Prerequisites](#publish-api-prereq)
+ [Step 1: Update the API resource policy](#update-API-resource-policy)
+ [Step 2: Create an API data set](#create-api-data-set)
+ [Step 3: Create a revision](#create-api-revision)
+ [Step 4: Add API assets to a revision](#add-api-asset)
+ [Step 5: Publish a new product containing APIs](#publish-api-data-product)
+ [Step 6: (Optional) Copy a product](#copy-api-product)
## Prerequisites
Before you can publish a product containing APIs, you must meet the following prerequisites:
+ Before you can use any AWS service, including AWS Data Exchange, you must sign up for AWS and create an administrative user. For more information, see [Getting started](https://docs.aws.amazon.com//singlesignon/latest/userguide/getting-started.html) in the *AWS IAM Identity Center User Guide*.
+ To create products on AWS Data Exchange, you must register your AWS account as an AWS Marketplace Seller. Use this account to create your data sets. The account with the API Gateway resource doesn't need to be in the same account that is creating the data sets.
+ Your REST API must be on Amazon API Gateway with an integration that uses an appropriate request and response model for accessing your data, such as Amazon DynamoDB or AWS Lambda. For more information, see [Developing a REST API in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-develop.html) and [Working with REST APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html) in the *Amazon API Gateway Developer Guide*.
**Note**
Only public API Gateway APIs are supported.
+ Your API Gateway REST API must be able to authenticate and authorize calls from the AWS Data Exchange service principal. Every request from AWS Data Exchange to your API uses the Signature Version 4 (SigV4) protocol signed with AWS Data Exchange credentials. AWS Data Exchange works with custom domains and domain key mappings.
**Note**
AWS Data Exchange doesn't support Amazon Cognito, No-Auth, and AWS Lambda authorizers.
+ If your API Gateway REST API uses a custom identity system for authentication and authorization, configure it to use IAM authentication and import an OpenAPI schema describing your API. AWS Data Exchange will invoke your API Gateway REST API with its own service credentials and include subscriber information such as account ID.
+ Your API Gateway REST API is responsible for integrating with your backend. To do this, do one of the following:
+ Attach a long-lived authentication token to every request that comes through your API Gateway REST API that the backend can verify.
+ Use API Gateway to invoke a Lambda function that can generate credentials and invoke your API.
Your API is invoked per the [API integration request specification](#api-request-spec).
For more information, see the following topics:
**Topics**
+ [API data set security](#api-data-set-security)
+ [API integration request specification](#api-request-spec)
+ [Header forwarding](#header-forwarding)
### API data set security
AWS Data Exchange encrypts traffic end to end using Transport Layer Security (TLS) 1.2. All metadata is encrypted at rest. AWS Data Exchange will not store subscriber requests or the responses from your backend. We only extract metering metadata necessary for billing.
### API integration request specification
An API on AWS Data Exchange passes through all headers (except for the headers listed in [Header forwarding](#header-forwarding)), body, http method, path, and query strings as-is from the customer request and appends the following headers.
```
// These headers help prevent Confused Deputy attacks. They enable the SourceAccount
// and SourceArn variables in IAM policies.
'x-amz-source-account': ACCOUNT_ID,
'x-amz-source-arn': `arn:aws:dataexchange:${REGION}:${OWNER_ACCOUNT_ID}:data-sets/${DATA_SET_ID}/revisions/${REVISION_ID}/assets/${ASSET_ID}`,
// These headers identify the API Asset in Data Exchange.
'x-amzn-dataexchange-asset-id': ASSET_ID,
'x-amzn-dataexchange-data-set-id': DATA_SET_ID,
'x-amzn-dataexchange-revision-id': REVISION_ID,
// This header identifies the Data Exchange Product.
'x-amzn-dataexchange-product-id': PRODUCT_ID,
// This header identifies the caller of Data Exchange. It will contain subscriber
// information.
'x-amzn-dataexchange-requester-account-id': REQUESTER_ACCOUNT_ID,
// Providers can attach custom metadata in the form of key/value pairs
// to a particular subscription. We will send these key/value pairs as stringified
// JSON.
'x-amz-dataexchange-subscription-metadata': STRINGIFIED_METADATA,
```
### Header forwarding
AWS Data Exchange removes any headers related to authentication or namespaced to Amazon prior to forwarding it to a provider backend. Specifically, AWS Data Exchange removes:
+ `Authentication` header
+ Any headers that begin with `x-amz`
The `host` header will be overwritten as a consequence of the proxying.
## Step 1: Update the API resource policy
If you have an Amazon API Gateway REST API that meets the [Prerequisites](#publish-api-prereq), you must update your API resource policy to grant AWS Data Exchange the ability to invoke your API when a subscriber makes a request to get your API’s schema.
**To update your API resource policy**
1. Add the following policy to your API’s resource policy:
```
{
"Effect": "Allow",
"Principal": {"Service": "dataexchange.amazonaws.com"},
"Action": "execute-api:Invoke",
"Resource": "*",
"Condition": {"StringEquals": {"aws:SourceAccount": ""}}
}
```
1. Replace `account-id` with the account that will be creating the API data set.
The account with the API Gateway resource does not need to be in the same account that is creating the data set.
This policy restricts these permissions to calls made by the AWS Data Exchange service principal and requires that only your account can authorize AWS Data Exchange to integrate with your API.
**Note**
If you have a resource policy that explicitly denies AWS Data Exchange from doing this invocation, you must remove or limit this deny.
You’re now ready to [create an API data set](#create-api-data-set).
## Step 2: Create an API data set
Data sets in AWS Data Exchange are dynamic and are versioned using revisions, with each revision containing at least one asset. For more information, see [Data in AWS Data Exchange](data-sets.md).
You use either the AWS Data Exchange console or the AWS Command Line Interface to create an API data set:
+ [Creating an API data set (console)](#create-api-ds-console)
+ [Creating an API data set (AWS CLI)](#create-api-ds-cli)
### Creating an API data set (console)
**To create an API data set (console)**
1. Open your web browser and sign in to the [AWS Data Exchange console](https://console.aws.amazon.com/dataexchange).
1. On the left side navigation pane, under **My data**, choose **Owned data sets**.
1. In **Owned data sets**, choose **Create data set** to open the **Data set creation steps** wizard.
1. In **Select data set type**, choose **Amazon API Gateway API**.
1. In **Define data set**, enter a **Name** and **Description** for your data set. For more information, see [Data set best practices](data-sets.md#data-set-best-practices).
1. (Optional) Under **Add tags – optional**, add tags.
1. Choose **Create**.
You are now ready to create a revision.
### Creating an API data set (AWS CLI)
**To create an API data set (CLI)**
1. Use the `create-data-set` command to create an API data set:
```
$ AWS dataexchange create-data-set \
--asset-type API_GATEWAY_API \
--description 'Data Set Description' \
--name 'Data Set Name'
{
"Arn": "arn:aws:dataexchange:us-east-1:123456789012:data-sets/$DATA_SET_ID",
"AssetType": "API_GATEWAY_API",
"CreatedAt": "2021-09-11T00:16:46.349000+00:00",
"Description": "Data Set Description",
"Id": "$DATA_SET_ID",
"Name": "Data Set Name",
"Origin": "OWNED",
"UpdatedAt": "2021-09-11T00:16:46.349000+00:00"
}
```
1. Note the new Asset Type of `API_GATEWAY_API`.
You are now ready to create a revision.
## Step 3: Create a revision
In the following procedure, you create a revision after you’ve created a data set. For more information, see [Revisions](data-sets.md#revisions).
You use either the AWS Data Exchange console or the AWS Command Line Interface to create a revision:
+ [Creating a revision (console)](#create-api-revision-console)
+ [Creating a revision (AWS CLI)](#create-api-revision-cli)
### Creating a revision (console)
**To create a revision (console)**
1. On the **Data set overview** section of the data set details page:
1. (Optional) Choose **Edit name** to edit information about your data set.
1. (Optional) Choose **Delete** to delete the data set.
1. On the **Revisions** section, choose **Create revision**.
1. Under **Define revision**, provide an optional comment for your revision that describes the purpose of the revision.
1. (Optional) Under **Add tags – optional**, add tags associated with the resource.
1. Choose **Create revision**.
1. Review, edit, or delete your changes from the previous step.
You are now ready to [add API assets to the revision](#add-api-asset).
### Creating a revision (AWS CLI)
**To create a revision (AWS CLI)**
1. Use the `create-revision` command to create a revision:
```
$ AWS dataexchange create-revision \
--data-set-id $DATA_SET_ID \
--comment 'First Atlas Revision'
{
"Arn": "arn:aws:dataexchange:us-east-1:123456789012:data-sets/$DATA_SET_ID/revisions/$REVISION_ID",
"Comment": "First Atlas Revision",
"CreatedAt": "2021-09-11T00:18:49.160000+00:00",
"DataSetId": "$DATA_SET_ID",
"Finalized": false,
"Id": "$REVISION_ID",
"UpdatedAt": "2021-09-11T00:18:49.160000+00:00"
}
```
1. [Add the API assets to the revision](#add-api-asset).
**Note**
You will need to know the ID of the API Gateway REST API you want to import as well as the stage.
## Step 4: Add API assets to a revision
API assets contain the information subscribers need to make calls to your API. For more information, see [Assets](data-sets.md#assets).
In the following procedure, you import data assets, and then finalize the revision.
You use either the AWS Data Exchange console or the AWS CLI to add assets to a revision:
+ [Adding API assets to a revision (console)](#add-api-assets)
+ [Adding API assets to a revision (AWS CLI)](#add-api-assets-cli)
### Adding API assets to a revision (console)
**To add assets to the revision (console)**
1. Under the **API assets** section of the data set details page, choose **Add API stage**.
1. Under **Select API stage**, for **Amazon API Gateway API**, enter an API in the input box or choose one of the following from the drop-down list:
+ **API in another AWS account** – this is a cross account API that you have been given permission to access.
+ **In this AWS account** – this is an API in your AWS account.
1. If you chose **API in another AWS account**, enter the API ID and the API **Stage name** in the input boxes.
1. If you chose **In this AWS account**, choose the API **Stage name** from the drop-down list
**Note**
You can create a new API stage by choosing **Create new** and following the steps in the **Create new API on Amazon API Gateway** modal. Once the new stage has been created, repeat Step 2.
1. Under **Advanced configuration – optional**, you can choose to **Connect existing Amazon API Gateway usage plan** to use the throttling and quota limits as defined in the existing usage plan, and enter the **API key**.
1. Under **Document API for subscribers**, provide details about the API that the subscribers will see after they subscribe to your product.
1. For **API name**, enter a name that subscribers can use to identify the API asset.
**Note**
If an **In this AWS account** was selected, the **API name** is automatically populated, which you can modify if necessary.
If a **API in another AWS account** was selected, the **API name** is populated with a default name, which you should modify to so the subscriber can easily understand what it is.
1. For **OpenAPI 3.0 specification**, either:
1. Enter or copy and paste the OpenAPI 3.0 specification file.
1. Choose **Import from .JSON file**, and then select the .json file from your local computer to import.
The imported specification appears in the box.
1. Choose **Import from Amazon API Gateway**, and then choose a specification to import.
The imported specification appears in the box.
1. For **Additional documentation - optional**, enter any additional information that is useful for the subscriber to know about your API. Markdown is supported.
**Note**
You can't edit the OpenAPI specification and additional documentation after you add this asset to a revision.
If you want to update this information, and the revision is not finalized, you can replace the asset.
If you want to update this information, and the revision is finalized, you can create a new revision with the updated asset.
1. Choose **Add API stage**.
A job is started to import your asset (in this case, the API) into your data set.
**Note**
If you do not have an API on Amazon API Gateway, you will be prompted to create one.
1. After the job is finished, the **State** field in the **Jobs** section is updated to **Completed.**
1. If you have more APIs to add, repeat Step 2.
1. Under **Revision overview**, review your revision and its assets.
1. Choose **Finalize**.
You have successfully finalized a revision for a data set.
You can [edit a revision](#edit-api-revision) or [delete a revision](#delete-api-revision) before you add it to a product.
You are now ready to [publish a new API data product](#publish-api-data-product).
### Adding API assets to a revision (AWS CLI)
You can add API assets by running an `IMPORT_ASSET_FROM_API_GATEWAY_API` job.
**To add API assets to a revision (AWS CLI):**
1. Use the `create-job` command to add API assets to the revision:
```
$ AWS dataexchange create-job \
--type IMPORT_ASSET_FROM_API_GATEWAY_API \
--details '{"ImportAssetFromApiGatewayApi":{"DataSetId":"$DATA_SET_ID","RevisionId":"$REVISION_ID","ApiId":"$API_ID","Stage":"$API_STAGE","ProtocolType":"REST"}}'
{
"Arn": "arn:aws:dataexchange:us-east-1:123456789012:jobs/$JOB_ID",
"CreatedAt": "2021-09-11T00:38:19.875000+00:00",
"Details": {
"ImportAssetFromApiGatewayApi": {
"ApiId": "$API_ID",
"DataSetId": "$DATA_SET_ID",
"ProtocolType": "REST",
"RevisionId": "$REVISION_ID",
"Stage": "$API_STAGE"
}
},
"Id": "$JOB_ID",
"State": "WAITING",
"Type": "IMPORT_ASSET_FROM_API_GATEWAY_API",
"UpdatedAt": "2021-09-11T00:38:19.875000+00:00"
}
$ AWS dataexchange start-job --job-id $JOB_ID
$ AWS dataexchange get-job --job-id $JOB_ID
{
"Arn": "arn:aws:dataexchange:us-east-1:0123456789012:jobs/$JOB_ID",
"CreatedAt": "2021-09-11T00:38:19.875000+00:00",
"Details": {
"ImportAssetFromApiGatewayApi": {
"ApiId": "$API_ID",
"DataSetId": "$DATA_SET_ID",
"ProtocolType": "REST",
"RevisionId": "$REVISION_ID",
"Stage": "$API_STAGE"
"ApiEndpoint": "string",
"ApiKey": "string",
"ApiName": "string",
"ApiDescription": "string",
"ApiSpecificationDownloadUrl": "string",
"ApiSpecificationDownloadUrlExpiresAt": "string"
}
},
"Id": "$JOB_ID",
"State": "COMPLETED",
"Type": "IMPORT_ASSET_FROM_API_GATEWAY_API",
"UpdatedAt": "2021-09-11T00:38:52.538000+00:00"
}
```
1. Use the `list-revision-assets` command to confirm that the new asset was created properly:
```
$ AWS dataexchange list-revision-assets \
--data-set-id $DATA_SET_ID \
--revision-id $REVISION_ID
{
"Assets": [
{
"Arn": "arn:aws:dataexchange:us-east-1:123456789012:data-sets/$DATA_SET_ID/revisions/$REVISION_ID/assets/$ASSET_ID",
"AssetDetails": {
"ApiGatewayApiAsset": {
"ApiEndpoint": "https://$API_ID.execute-api.us-east-1.amazonaws.com/$API_STAGE",
"ApiId": "$API_ID",
"ProtocolType": "REST",
"Stage": "$API_STAGE"
}
},
"AssetType": "API_GATEWAY_API",
"CreatedAt": "2021-09-11T00:38:52.457000+00:00",
"DataSetId": "$DATA_SET_ID",
"Id": "$ASSET_ID",
"Name": "$ASSET_ID/$API_STAGE",
"RevisionId": "$REVISION_ID",
"UpdatedAt": "2021-09-11T00:38:52.457000+00:00"
}
]
}
```
You are now ready to [publish the API data product](#publish-api-data-product).
### Edit a revision
**To edit the revision after you’ve finalized it**
1. On the **Revision overview**, choose **De-finalize**.
You see a message that the revision is no longer in the finalized state.
1. To edit the revision, from **Revision overview**, choose **Actions**, **Edit**.
1. Make your changes, and then choose **Update**.
1. Review your changes and then choose **Finalize**.
### Delete a revision
**To delete the revision after you’ve finalized it**
1. On the **Revision overview**, choose **Delete**.
1. Type **Delete** in the **Delete revision** dialog box, and then choose **Delete**.
**Warning**
This deletes the revision and all of its assets. This action cannot be undone.
## Step 5: Publish a new product containing APIs
After you've created at least one data set and finalized a revision with assets, you're ready to publish that data set as a part of a product. For more information, see [Product best practices in AWS Data Exchange](product-details.md). Make sure that you have all required details about your product and offer.
You use the AWS Data Exchange console or the AWS Marketplace Catalog API to publish a new product containing APIs. For more information about how to publish a new product using the AWS Marketplace Catalog API, see [Using AWS Data Exchange with the AWS Marketplace Catalog API](appendices.md).
+ [Publishing a new product containing APIs (console)](#publish-api-product-console)
### Publishing a new product containing APIs (console)
**To publish a new product containing APIs**
1. From the left navigation pane of the [AWS Data Exchange console](https://console.aws.amazon.com/dataexchange), under **Publish data**, choose **Products**.
1. From **Products**, choose **Publish new product** to open the **Publish new product** wizard.
1. In **Product visibility**:
1. Choose your product's **Product visibility options** as either **Public** or **Private**.
All AWS Data Exchange products with visibility set to **Public** require a public offer.
For more information, see [Product visibility in AWS Data Exchange](product-visibility.md).
1. Choose your product's **Sensitive information** configuration.
For more information, see [Sensitive categories of information in AWS Data Exchange](sensitive-information.md).
1. Choose **Next**.
1. In **Add data**:
1. Under **Owned data sets**, select the check boxes next to the data sets you want to add, and then choose **Add selected**.
**Note**
The data sets you choose must have a finalized revision. Data sets without finalized revisions aren't added.
1. Go to **Selected data sets** to review your selections.
You can review the **Name** of the data set, the **Type** of data set, and the timestamp of when the data set was **Last updated**.
1. Go to **Select revision access rules**, and choose the revision access rules that you want to set for data sets included in this product.
For more information, see [Revision access rules in AWS Data Exchange](best-practices-revisions.md).
1. Choose **Next**.
1. In **Define product**:
1. Under **Product overview**, enter information about your product, including the **Product name**, **Product logo**, **Support contact** information, and **Product categories**.
For more information, see [Product best practices in AWS Data Exchange](product-details.md).
1. (Optional) Under **Data dictionaries and samples – optional**, choose a data set by selecting the option button next to the data set name and then choose **Edit**.
1. In the **Edit** dialog box, choose **Upload** to upload a new data dictionary.
You can choose one data dictionary, in .csv format, with a maximum size of 1 MB.
1. Choose a saved data dictionary from your computer and then choose **Open**.
The data dictionary .csv file appears on the **Edit** dialog box.
**Note**
Your data dictionary must conform to the AWS Data Exchange data dictionary template. If you don’t have a saved data dictionary to upload, you can choose either the **blank data dictionary template** link or the **example data dictionary** link in the AWS Data Exchange console.
1. Choose **Data dictionary preview** to preview the data dictionary.
1. Under **Samples - optional**, choose **Upload samples**, choose a sample from your computer, and then choose **Open**.
The samples appear on the **Edit** dialog box.
**Note**
You can upload up to 10 samples with a maximum size of 50 MB. Samples in .csv format can be previewed.
1. Enter a description for each sample that will be visible on the product detail page.
1. Choose **Save**.
1. Under **Product definition**, enter a **Short description** and a **Long description** of your product.
If you want to use a template for your long description, select **Apply template**, choose your template type, and then fill out the template with your specific product details.
1. Choose **Next**.
1. Configure your offer in either **Add public offer** (for public offer) or **Add custom offer** (for private offers):
All AWS Data Exchange products with visibility set to **Public** require a public offer.
1. For private offers only:
1. Choose one of the listed **Offer types**: **Private offer**, **Renewed private offer**, or **Bring Your Own Subscription (BYOS)**.
1. In the **Subscriber account information** section, add at least one subscriber account to which you want to extend the offer.
1. Choose your **Pricing and access duration** options for the subscription.
1. For **Metered costs - optional**, choose **Add**.
1. For **Add metered cost**, select the type of cost for the API call from the **Type** list:
+ **Per API request**
+ **Per successful API request**
+ **Per unit of data transferred in bytes**
+ **New custom metered cost**
1. Enter or update the **Cost display name**, which is visible on the subscriber’s invoice.
1. If you're using a **Pre-defined metered cost**, the **Key** is automatically generated, can’t be edited, and doesn’t need to be sent back in the response header.
1. If you're creating a **New custom metered cost**, enter the **Key**, which is the identifier for the metered cost in the API response header (15 characters maximum).
This **Key** should be sent back as part of the `x-amz-dataexchange-metering` response header.
**Example Custom key**
If you have a custom key called **VertexCount** and another custom key called **EdgeCount**, the “x-amz-dataexchange-metering” response header could have a value of `VertexCount=3,EdgeCount=10` or you could return two separate header lines:
`x-amz-dataexchange-metering: VertextCount=3`
`x-amz-dataexchange-metering: EdgeCount=10`
1. Enter the price the subscriber is charged per unit in **Price / unit**.
1. (Optional) Enter the number of units to display an example of the cost in the **Metered cost calculator**.
1. (Optional) Enter a brief **Description** of the metered cost that appears on the product detail page.
1. Choose **Add**.
1. (Optional) Repeat to add additional metered costs.
The order of the metered costs appears on the product detail page. You can’t reorder them.
**Note**
After the offer is created, you can edit the price and description of a metered cost. For more information, see [Updating product and offer details in AWS Data Exchange](update-product-details.md).
1. For private offers only, choose the **Offer expiration date** by which the subscriber must accept the offer.
1. Choose your **Tax settings**, **Data subscription agreement (DSA)**, and **Refund policy**.
1. (Optional) For public offers only, set **Subscription verification**, which enables you to control who can subscribe to this product. For more information, see [Subscription verification for providers in AWS Data Exchange](subscription-verification-pro.md).
1. Choose your **Offer auto-renewal** option. For more information, see [Creating an offer for AWS Data Exchange products](prepare-offers.md).
1. Choose **Next**.
1. In the **Review & publish** section, review your product information.
1. Expand the **Product page preview** to see how the product page will look after publication.
1. (Optional) Choose the **Edit** button in any section to edit that section.
1. If you're sure that you want to make the product and public offer visible and available to everyone, choose **Publish**.
You've now completed the manual portion of publishing a data product with a public offer. AWS Data Exchange prepares and publishes your product.
On the **Product overview** page, the status of your product is **Awaiting approval** and then changes to **Published** after it's published.
## Step 6: (Optional) Copy a product
After you have created your first product, you can copy its details and public offers to create a new product.
**Note**
You can copy a public, private, published, or unpublished product. Custom offers associated with the product will not be copied, but public offers will be copied.
**To copy a product**
1. Open your web browser and sign in to the [AWS Data Exchange console](https://console.aws.amazon.com/dataexchange).
1. From the left navigation pane, under **Publish data**, choose **Products**.
1. From **Products**, choose the button next to the product you want to copy.
1. Select the **Actions** dropdown, and then choose **Create copy**.
1. Continue through the **Publish a new product** workflow, with details already filled in, based on the product you chose in Step 3. For more information, see [Step 5: Publish a new product](publish-data-product.md#publish-products).