Menu
Amazon API Gateway
Developer Guide

Build an API Gateway API with AWS Integration

Both the Build an API Gateway API with Lambda Proxy Integration and Build an API Gateway API with Lambda Integration topics describe how to create an API Gateway API to expose the integrated Lambda function. In addition, you can create an API Gateway API to expose other AWS services, such as Amazon SNS, Amazon S3, Amazon Kinesis, and even AWS Lambda. This is made possible by the AWS integration. The Lambda integration or the Lambda proxy integration is a special case, where the Lambda function invocation is exposed through the API Gateway API.

All AWS services support dedicated APIs to expose their features. However, the application protocols or programming interfaces are likely to differ from service to service. An API Gateway API with the AWS integration has the advantage of providing a consistent application protocol for your client to access different AWS services.

In this walkthrough, we create an API to expose Amazon SNS. For more examples of integrating an API with other AWS services, see Samples and Tutorials.

Unlike the Lambda proxy integration, there is no corresponding proxy integration for other AWS services. Hence, an API method is integrated with a single AWS action. For more flexibility, similar to the proxy integration, you can set up a Lambda proxy integration. The Lambda function then parses and processes requests for other AWS actions.

API Gateway does not retry when the endpoint times out. The API caller must implement retry logic to handle endpoint timeouts.

This walkthrough builds on the instructions and concepts in Build an API Gateway API with Lambda Integration.If you have not yet completed that walkthrough, we suggest that you do it first.

Prerequisites

Before you begin this walkthrough, do the following:

  1. Complete the steps in Get Ready to Build an API Gateway API.

  2. Ensure that the IAM user has access to create policies and roles in IAM. You need to create an IAM policy and role in this walkthrough.

  3. Create a new API named MyDemoAPI. For more information, see Build an API with HTTP Custom Integration.

  4. Deploy the API at least once to a stage named test. For more information, see Deploy the API in Build an API Gateway API with Lambda Integration.

  5. Complete the rest of the steps in Build an API Gateway API with Lambda Integration.

  6. Create at least one topic in Amazon Simple Notification Service (Amazon SNS). You will use the deployed API to get a list of topics in Amazon SNS that are associated with your AWS account. To learn how to create a topic in Amazon SNS, see Create a Topic. (You do not need to copy the topic ARN mentioned in step 5.)

Step 1: Create the Resource

In this step, you create a resource that enables the AWS service proxy to interact with the AWS service.

To create the resource

  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. If MyDemoAPI is displayed, choose Resources.

  3. In the Resources pane, choose the resource root, represented by a single forward slash (/), and then choose Create Resource.

  4. For Resource Name, type MyDemoAWSProxy, and then choose Create Resource.

Step 2: Create the GET Method

In this step, you create a GET method that enables the AWS service proxy to interact with the AWS service.

To create the GET method

  1. In the Resources pane, choose /mydemoawsproxy, and then choose Create Method.

  2. For the HTTP method, choose GET, and then save your choice.

Step 3: Create the AWS Service Proxy Execution Role

In this step, you create an IAM role that your AWS service proxy uses to interact with the AWS service. We call this IAM role an AWS service proxy execution role. Without this role, API Gateway cannot interact with the AWS service. In later steps, you specify this role in the settings for the GET method you just created.

To create the AWS service proxy execution role and its policy

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. Choose Policies.

  3. Do one of the following:

    • If the Welcome to Managed Policies page appears, choose Get Started, and then choose Create Policy.

    • If a list of policies appears, choose Create Policy.

  4. Next to Create Your Own Policy, choose Select.

  5. For Policy Name, type a name for the policy (for example, APIGatewayAWSProxyExecPolicy).

  6. For Description, type Enables API Gateway to call AWS services.

  7. For Policy Document, type the following, and then choose Create Policy.

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Resource": [ "*" ], "Action": [ "sns:ListTopics" ] } ] }

    This policy document allows the caller to get a list of the Amazon SNS topics for the AWS account.

  8. Choose Roles.

  9. Choose Create Role.

  10. Choose AWS Service under Select role type and then choose API Gateway.

  11. Choose Next: Permissions.

  12. Choose Next: Review.

  13. For Role Name, type a name for the execution role (for example, APIGatewayAWSProxyExecRole), optionally, type a description for this role, and then choose Create role.

  14. In the Roles list, choose the role you just created. You may need to scroll down the list.

  15. For the selected role, choose Attach policy.

  16. Select the check box next to the policy you created earlier (APIGatewayAWSProxyExecPolicy) and choose Attach policy.

  17. The role you just created has the following trust relationship that enables API Gateway assume to role for any actions permitted by the attached policies:

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

    For Role ARN, note of the Amazon Resource Name (ARN) for the execution role. You need it later. The ARN should look similar to: arn:aws:iam::123456789012:role/APIGatewayAWSProxyExecRole, where 123456789012 is your AWS account ID.

Step 4: Specify Method Settings and Test the Method

In this step, you specify the settings for the GET method so that it can interact with an AWS service through an AWS service proxy. You then test the method.

To specify settings for the GET method and then test it

  1. In the API Gateway console, in the Resources pane for the API named MyDemoAPI, in /mydemoawsproxy, choose GET.

  2. In the Setup pane, for Integration type, choose Show advanced, and then choose AWS Service Proxy.

  3. For AWS Region, choose the name of the AWS Region where you want to get the Amazon SNS topics.

  4. For AWS Service, choose SNS.

  5. For HTTP method, choose GET.

  6. For Action, type ListTopics.

  7. For Execution Role, type the ARN for the execution role.

  8. Leave Path Override blank.

  9. Choose Save.

  10. In the Method Execution pane, in the Client box, choose TEST, and then choose Test. If successful, Response Body displays a response similar to the following:

    Copy
    { "ListTopicsResponse": { "ListTopicsResult": { "NextToken": null, "Topics": [ { "TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-1" }, { "TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-2" }, ... { "TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-N" } ] }, "ResponseMetadata": { "RequestId": "abc1de23-45fa-6789-b0c1-d2e345fa6b78" } } }

Step 5: Deploy the API

In this step, you deploy the API so that you can call it from outside of the API Gateway console.

To deploy the API

  1. In the Resources pane, choose Deploy API.

  2. For Deployment stage, choose test.

  3. For Deployment description, type Calling AWS service proxy walkthrough.

  4. Choose Deploy.

Step 6: Test the API

In this step, you go outside of the API Gateway console and use your AWS service proxy to interact with the Amazon SNS service.

  1. In the Stage Editor pane, next to Invoke URL, copy the URL to the clipboard. It should look like this:

    Copy
    https://my-api-id.execute-api.region-id.amazonaws.com/test
  2. Paste the URL into the address box of a new browser tab.

  3. Append /mydemoawsproxy so that it looks like this:

    Copy
    https://my-api-id.execute-api.region-id.amazonaws.com/test/mydemoawsproxy

    Browse to the URL. Information similar to the following should be displayed:

    Copy
    {"ListTopicsResponse":{"ListTopicsResult":{"NextToken": null,"Topics":[{"TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-1"},{"TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-2"},...{"TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-N}]},"ResponseMetadata":{"RequestId":"abc1de23-45fa-6789-b0c1-d2e345fa6b78}}}

Step 7: Clean Up

You can delete the IAM resources the AWS service proxy needs to work.

Warning

If you delete an IAM resource an AWS service proxy relies on, that AWS service proxy and any APIs that rely on it will no longer work. Deleting an IAM resource cannot be undone. If you want to use the IAM resource again, you must re-create it.

To delete the associated IAM resources

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the Details area, choose Roles.

  3. Select APIGatewayAWSProxyExecRole, and then choose Role Actions, Delete Role. When prompted, choose Yes, Delete.

  4. In the Details area, choose Policies.

  5. Select APIGatewayAWSProxyExecPolicy, and then choose Policy Actions, Delete. When prompted, choose Delete.

You have reached the end of this walkthrough. For more detailed discussions about creating API as an AWS service proxy, see Create an API as an Amazon S3 Proxy, Create an API Gateway API for AWS Lambda Functions, or Create an API Gateway API as an Amazon Kinesis Proxy.