Manage API deployments to Amazon API Gateway in Postman

Amazon API Gateway enables developers to publish and manage APIs that access AWS and other web services and data sources. Once connected to API Gateway, you can view your API deployment status and history from within Postman. You can also view Amazon CloudWatch metrics for each stage to get operational insight into your API.

This integration supports OpenAPI 3.0 definitions for HTTP and REST APIs. You can import a definition from Amazon API Gateway and use it in Postman. For HTTP APIs, you can choose to export your definition from Postman to API Gateway. You can use the AWS console to deploy your exported definition to a stage, or deploy your HTTP API definition directly from Postman to a stage.

Connecting to Amazon API Gateway

To connect to Amazon API Gateway in Postman, select APIs in the sidebar and select an API. Select Deployments, and then select AWS API Gateway.

When setting up the connection to API Gateway, you can choose to authenticate by creating an AWS IAM role or by using an AWS access key. Follow the steps for your chosen method:

• Authenticating with an AWS IAM role
• Authenticating with an AWS access key

When you delete an API or remove it from a workspace, any configured integrations aren't deleted or removed. On the Postman Home page, select Integrations and search for "AWS API Gateway" to view the list of AWS API gateway integrations. To delete an integration, select it and then select Delete Integration.

Authenticating with an AWS IAM role

To set up a connection to Amazon API Gateway using an AWS IAM role, select IAM under AWS Authentication Mechanism.

Enter a Nickname for this integration and select the AWS API Type (HTTP or REST).

To create an IAM role for Postman in AWS, do the following:

1. Sign in to the AWS IAM console and select Create role.

2. Under Select trusted entity, select AWS account.

3. Under An AWS account, select Another AWS account and enter Postman's AWS Account ID: 258201882842

4. Under Options, select the Require external ID checkbox and enter the External ID from Postman. You can find the external ID in Postman's Connect to AWS API Gateway procedure above, in Step 1: Create an IAM role.

   For more information, refer to the AWS IAM guide on using external IDs.

5. Select Next: Permissions.

6. Select an existing IAM policy or select Create policy. If you are creating a policy, use the following JSON code:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "Stmt909923626743",
               "Effect": "Allow",
               "Action": [
                   "apigateway:GET",
                   "apigateway:PUT",
                   "apigateway:POST",
                   "cloudwatch:GetMetricData"
               ],
               "Resource": [
                   "*"
               ]
           }
       ]
   }
   

   This policy will enable exporting and deploying for HTTP API definitions. (Exporting and deploying aren't supported for REST API definitions.) You can customize the Action section in the IAM policy based on your needs:

   • "apigateway:GET" - (Required) Enables viewing API Gateway deployments for HTTP and REST APIs in Postman.
   • "apigateway:PUT" - Enables exporting HTTP API definitions to the API Gateway.
   • "apigateway:POST" - Enables deploying HTTP API definitions to a stage on the API Gateway.
   • "apigateway:*" - Assigns all GET, PUT, POST, PATCH, DELETE permissions to the IAM role.
   • "cloudwatch:GetMetricData" - Enables viewing CloudWatch metrics in Postman.

7. Select Next: Tags.

8. Select Next: Review.

9. Add a Role name and Role description, then select Create role.

Copy the Role ARN from AWS and paste it in Postman under Step 2: Enter role ARN and region. Next, enter the AWS Region where the API Gateway is located and select the API Gateway. When you're ready, select Connect.

Authenticating with an AWS access key

To set up a connection to Amazon API Gateway using an AWS access key, select Access Key under AWS Authentication Mechanism.

Next, enter information about the connection:

• Enter a Nickname for this integration.
• Select the AWS API Type (HTTP or REST).
• Enter the Access Key ID and Secret Access Key for your AWS account. (Learn how to find your credentials in AWS.)
• Enter the AWS Region where the API Gateway is located and select the API Gateway.

When you're ready, select Connect.

Importing a definition

After setting up the connection, you can choose to import an HTTP or REST definition from the API Gateway:

• To import a definition, select the AWS stage to import the definition from and select Import. Importing a definition will replace your current API definition or add a new definition if one doesn't exist.
• If you don't want to import a definition, select Maybe later. You can import a definition at any time after connecting to Amazon API Gateway.

Viewing Amazon API Gateway deployments

After connecting to Amazon API Gateway, you can view the export and deployment history for your API definitions in Postman. Select APIs in the sidebar and select an API. Select Deployments.

• For each stage you can view the active deployment and the date last updated. You can also view CloudWatch metrics for the last week, such as average latency and the number of 4xx and 5xx errors.
  • Select the arrow next to a stage to view more details, including the invoke URL and stage description (from AWS).
  • Select a stage name to view metrics on the CloudWatch dashboard.
• For each export from Postman, you can view the source of the export and the time when exported.
• For each deployment you can view the deployment ID, description, and creation date.

From the Deployments view, you can take the following actions:

• To view your API Gateway in AWS, select the AWS Gateway ID.
• To export or deploy an HTTP definition to the API Gateway, select Deploy API. Learn more about deploying your API.
• To import a definition from the API Gateway, select Import Definition. Learn more about importing a definition.
• To view metrics for your API Gateway in AWS, select View Dashboard.
• For information about the latest deployment status, select the refresh icon .
• To edit or delete the connection to Amazon API Gateway, select the more actions icon .

Viewing CloudWatch metrics

Amazon CloudWatch provides monitoring and observability for APIs deployed to Amazon API Gateway. By default, API Gateway metrics data is automatically sent to CloudWatch in one-minute intervals. After connecting to API Gateway, you can view the last week of CloudWatch metrics in Postman.

From the Deployments view, select the name of a stage to view the CloudWatch dashboard for that stage. The graphs on the dashboard display metrics for latency, integration latency, 4xx and 5xx error rates, and count.

• Hover over a data point on a graph to view detailed metrics data.
• Hover over the information icon for a specific graph to learn more about the metrics.

From the CloudWatch dashboard, you can take the following actions:

• To view metrics for a different stage, select the stage in the dropdown list.
• To view metrics for a different time range, select the time range in the dropdown list.
• To view metrics for your API Gateway in AWS, select View Dashboard.
• To view the this stage in AWS, select View Stage on AWS.
• To view the latest CloudWatch metrics, select the refresh icon .

Updating an existing IAM policy for CloudWatch

The Amazon API Gateway integration supports viewing CloudWatch metrics in Postman. If you previously created an IAM policy when configuring the integration, you may need to update the policy to enable CloudWatch metrics. Make sure to add the "cloudwatch:GetMetricData" action to your IAM policy:

"Action": [
    "apigateway:GET",
    "apigateway:PUT",
    "apigateway:POST",
    "cloudwatch:GetMetricData"
],

Importing a definition from Amazon API Gateway

You can import an HTTP or REST definition from a connected Amazon API Gateway to your API in Postman. Importing a definition will replace your current API definition or add a new definition if one doesn't exist.

1. Select APIs in the sidebar and select an API.
2. Select Deployments.
3. Select Import Definition.
4. Select the AWS stage to import the definition from.
5. Select Import.

Exporting and deploying your API

Exporting an HTTP API definition makes it available in the connected Amazon API Gateway. After you export a definition from Postman, use the AWS console to configure and deploy the definition to a stage in API Gateway. When exporting, you can also choose to deploy the definition directly from Postman to a stage in the connected API Gateway. Once the definition is deployed, users can start calling the API.

HTTP API definition can be exported and deployed from Postman. To deploy a REST API definition, use the AWS console.

To export and deploy your API definition to an AWS stage, do the following:

1. Select APIs in the sidebar and select an API.

2. Select Deployments.

3. Select Deploy API.

4. Select the source of the definition you want to deploy. You can select the current definition or any published version of the definition.

5. (Optional) If you would like to deploy the definition to a stage after exporting, select Deploy on a stage. Select the AWS stage to deploy the definition to, and enter a brief description.

   To deploy your definition, your gateway must have at least one route with a configured integration.

6. Select Deploy.

   If you have a problem exporting or deploying, make sure you've assigned both the PUT and POST permissions in your IAM policy.

API Gateway extensions to Open API (vendor extensions) are preserved when pushing and deploying a definition from Postman. Postman merges any extensions present in the API Gateway into the definition before pushing the merged definition to the API Gateway.