Selling an API Gateway API through AWS Marketplace
After you build, test, and deploy your API, you can package it in an API Gateway usage plan and sell the plan as a Software as a Service (SaaS) product through AWS Marketplace. API buyers subscribing to your product offering are billed by AWS Marketplace based on the number of requests made to the usage plan.
To sell your API on AWS Marketplace, you must set up the sales channel to integrate AWS Marketplace with API Gateway. Generally speaking, this involves listing your product on AWS Marketplace, setting up an IAM role with appropriate policies to allow API Gateway to send usage metrics to AWS Marketplace, associating an AWS Marketplace product with an API Gateway usage plan, and associating an AWS Marketplace buyer with an API Gateway API key. Details are discussed in the following sections.
To enable your customers to buy your product on AWS Marketplace, you must register your developer portal (an external application) with AWS Marketplace. The developer portal must handle the subscription requests that are redirected from the AWS Marketplace console.
For more information about selling your API as a SaaS product on AWS Marketplace, see AWS Marketplace SaaS Subscriptions - Seller Integration Guide.
Topics
Initialize AWS Marketplace Integration with API Gateway
The following tasks are for one-time initialization of AWS Marketplace integration with API Gateway, which enables you to sell your API as a SaaS product.
List a Product on AWS Marketplace
To list your usage plan as a SaaS product, submit a product load form through
AWS Marketplace. The
product must contain a dimension named apigateway
of the
requests
type. This dimension defines the price-per-request
and is used by API Gateway to meter requests to your API.
Create the Metering Role
Create an IAM role named ApiGatewayMarketplaceMeteringRole
with the following execution policy and trust policy. This role allows API Gateway to send
usage metrics to AWS Marketplace on your behalf.
Execution Policy of the Metering Role
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"aws-marketplace:BatchMeterUsage",
"aws-marketplace:ResolveCustomer"
],
"Resource": "*",
"Effect": "Allow"
}
]
}
Trusted Relationship Policy of the Metering Role
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
Associate Usage Plan with AWS Marketplace Product
When you list a product on AWS Marketplace, you receive an AWS Marketplace product code. To integrate
API Gateway with AWS Marketplace, associate your usage plan with the AWS Marketplace product code. You enable
the association by setting the API Gateway UsagePlan
's productCode field to
your AWS Marketplace product code, using the API Gateway console, the API Gateway REST API, the
AWS CLI for API Gateway, or AWS SDK for API Gateway. The following code example uses the API Gateway
REST API:
PATCH /usageplans/USAGE_PLAN_ID
Host: apigateway.region
.amazonaws.com
Authorization: ...
{
"patchOperations" : [{
"path" : "/productCode",
"value" : "MARKETPLACE_PRODUCT_CODE
",
"op" : "replace"
}]
}
Handle Customer Subscription to Usage Plans
The following tasks are handled by your developer portal application.
When a
customer
subscribes to your product through AWS Marketplace, AWS Marketplace forwards a POST
request to the SaaS subscriptions URL that you
registered when listing your product on AWS Marketplace. The POST
request comes with
an x-amzn-marketplace-token
header parameter containing buyer
information. Follow the instructions in the Register Application section of the SaaS Seller Integration Guide to handle this redirect in your developer
portal application.
Responding to a customer's subscribing request, AWS Marketplace sends a
subscribe-success
notification to an Amazon SNS topic that you can
subscribe to
(See
Step 6.4 of the SaaS Seller Integration Guide). To accept the customer subscription
request, you handle the subscribe-success
notification by creating or
retrieving an API Gateway API key for the customer, associating the customer's
AWS Marketplace-provisioned customerId
with the API keys, and then adding the API key
to your usage plan.
When the customer's subscription request completes, the developer portal application
should present the customer with the associated API key and inform the customer that the
API key must be included in the x-api-key
header in requests to the
API.
When a customer cancels a subscription to a usage plan, AWS Marketplace sends an
unsubscribe-success
notification to the SNS topic. To complete
the process of unsubscribing the customer, you handle the
unsubscribe-success
notification by removing the customer's API
keys from the usage plan.
Authorize a Customer to Access a Usage Plan
To authorize access to your usage plan for a given customer, use the API Gateway API to fetch or create an API key for the customer and add the API key to the usage plan.
The following example shows how to call the API Gateway REST API to create a new API key
with a specific AWS Marketplace customerId
value
(MARKETPLACE_CUSTOMER_ID
).
POST apikeys HTTP/1.1
Host: apigateway.region
.amazonaws.com
Authorization: ...
{
"name" : "my_api_key",
"description" : "My API key",
"enabled" : "false",
"stageKeys" : [ {
"restApiId" : "uycll6xg9a",
"stageName" : "prod"
} ],
"customerId" : "MARKETPLACE_CUSTOMER_ID
"
}
The following example shows how to get an API key with a specific AWS Marketplace
customerId
value
(MARKETPLACE_CUSTOMER_ID
).
GET apikeys?customerId=MARKETPLACE_CUSTOMER_ID
HTTP/1.1
Host: apigateway.region
.amazonaws.com
Authorization: ...
To add an API key to a usage plan, create a UsagePlanKey with the API
key for the relevant usage plan. The following example shows how to accomplish this
using the API Gateway REST API, where n371pt
is the usage plan ID and
q5ugs7qjjh
is an example API keyId
returned from
the preceding examples.
POST /usageplans/n371pt/keys HTTP/1.1
Host: apigateway.region
.amazonaws.com
Authorization: ...
{
"keyId": "q5ugs7qjjh",
"keyType": "API_KEY"
}
Associate a Customer with an API Key
You must update the ApiKey's
customerId
field to the AWS Marketplace customer ID of the customer.
This associates the API key with the AWS Marketplace customer, which enables metering and
billing for the buyer. The following code example calls the API Gateway REST API to do
that.
PATCH /apikeys/q5ugs7qjjh
Host: apigateway.region
.amazonaws.com
Authorization: ...
{
"patchOperations" : [{
"path" : "/customerId",
"value" : "MARKETPLACE_CUSTOMER_ID
",
"op" : "replace"
}]
}