# Deploy to Amazon API Gateway from the Postman API Builder

[Amazon API Gateway](https://aws.amazon.com/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](https://aws.amazon.com/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.

## Connect to Amazon API Gateway

To connect to Amazon API Gateway in Postman, click **APIs** in the sidebar and select an API. Click **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:

* [Authenticate with an AWS IAM role](#authenticate-with-an-aws-iam-role)
* [Authenticate with an AWS access key](#authenticate-with-an-aws-access-key)

<Info class="iconless-callout">
  When you delete an API or remove it from a workspace, any configured integrations aren't deleted or removed. On the Postman **Home** page, click **Integrations** and search for "AWS API Gateway" to view the list of [AWS API gateway integrations](https://go.postman.co/integrations/service/api_gateway_aws/api_gateway_aws). To delete an integration, select it and then click **Delete Integration**.
</Info>

### Authenticate 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**.

<img alt="Connecting with AWS IAM role" src="https://assets.postman.com/postman-docs/v10/connect-to-api-gateway-with-iam-role-v10.jpg" />

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](https://console.aws.amazon.com/iam/home#/roles) and click **Create role**.

2. Under **Select trusted entity**, click **AWS account**.

3. Under **An AWS account**, click **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 the **Connect to AWS API Gateway** screen in Postman.

   <Info class="iconless-callout">
     For more information, refer to the [AWS IAM guide on using external IDs](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html).
   </Info>

5. Click **Next: Permissions**.

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

   ```json
   {
       "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](#export-and-deploy-your-api) HTTP API definitions to the API Gateway.
   * `"apigateway:POST"` - Enables [deploying](#export-and-deploy-your-api) 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](#view-cloudwatch-metrics) in Postman.

7. Click **Next: Tags**.

8. Click **Next: Review**.

9. Add a **Role name** and **Role description**, then click **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, click **Connect**.

### Authenticate with an AWS access key

To set up a connection to Amazon API Gateway using an AWS access key, do the following:

1. Click **Access Key** under **AWS Authentication Mechanism**.

<img alt="Connecting with AWS access key" src="https://assets.postman.com/postman-docs/v10/connect-to-api-gateway-with-access-key-v10.jpg" />

1. 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](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/getting-your-credentials.html).)
   * Enter the **AWS Region** where the API Gateway is located and select the **API Gateway**.

2. Click **Connect**.

### Import 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 click **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, click **Maybe later**. You can [import a definition](#import-a-definition-from-amazon-api-gateway) at any time after connecting to Amazon API Gateway.

<img alt="Importing a definition" src="https://assets.postman.com/postman-docs/v10/connect-to-api-gateway-import-v10.jpg" />

## View Amazon API Gateway deployments

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

* You can view the active deployment and last updated date for each stage. You can also view CloudWatch metrics for the past week, such as average latency and the number of `4xx` and `5xx` errors.
  * Click 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](#view-cloudwatch-metrics).
* 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.

<img alt="Viewing API deployments" src="https://assets.postman.com/postman-docs/v10/api-gateway-deployments-tab-v10.jpg" />

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, click **Deploy API**. Learn more about [deploying your API](#export-and-deploy-your-api).
* To import a definition from the API Gateway, click **Import Definition**. Learn more about [importing a definition](#import-a-definition-from-amazon-api-gateway).
* To view metrics for your API Gateway in AWS, click **View Dashboard**.
* For information about the latest deployment status, click <img alt="Refresh icon" src="https://assets.postman.com/postman-docs/aether-icons/action-refresh-stroke.svg#icon" width="16px" /> **Refresh**.
* To edit or delete the connection to Amazon API Gateway, click <img alt="Options icon" src="https://assets.postman.com/postman-docs/aether-icons/action-options-stroke.svg#icon" width="16px" /> **View more actions**.

## View CloudWatch metrics

[Amazon CloudWatch](https://aws.amazon.com/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 <img alt="Info icon" src="https://assets.postman.com/postman-docs/aether-icons/state-info-stroke.svg#icon" width="16px" /> **Info** for a specific graph to learn more about the metrics.

<img alt="Viewing CloudWatch metrics" src="https://assets.postman.com/postman-docs/api-gateway-cloudwatch-metrics-v9-15.jpg" />

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, click **View Dashboard**.
* To view the this stage in AWS, click **View Stage on AWS**.
* To view the latest CloudWatch metrics, click <img alt="Refresh icon" src="https://assets.postman.com/postman-docs/aether-icons/action-refresh-stroke.svg#icon" width="16px" /> **Refresh**.

### Update an existing IAM policy for CloudWatch

The Amazon API Gateway integration supports viewing CloudWatch metrics in Postman. If you 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:

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

## Import 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 replaces your current API definition or add a new definition if one doesn't exist.*

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

<img alt="Importing a definition" src="https://assets.postman.com/postman-docs/v10/amazon-api-gateway-import-v10.jpg" />

## Export and deploy 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.

<Info class="iconless-callout">
  HTTP API definition can be exported and deployed from Postman. To deploy a REST API definition, use the AWS console.
</Info>

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

1. Click **APIs** in the sidebar and select an API.

2. Click **Deployments**.

3. Click **Deploy API**.

4. Select the source of the definition you want to deploy. You can select the current definition or any [published version](/docs/design-apis/api-builder/versioning-an-api/api-versions/) of the definition.

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

   <Info class="iconless-callout">
     To deploy your definition, your gateway must have at least one route with a configured integration.
   </Info>

6. Click **Deploy**.

   <Info class="iconless-callout">
     If you have a problem exporting or deploying, make sure you've assigned both the PUT and POST permissions [in your IAM policy](#authenticate-with-an-aws-iam-role).
   </Info>

<img alt="Deploying an API" src="https://assets.postman.com/postman-docs/v10/deploy-api-definition-on-aws-v10-0-15.jpg" />

<Info class="iconless-callout">
  [API Gateway extensions to Open API](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html) (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.
</Info>