Menu
Amazon API Gateway
Developer Guide

Create an AWS Service Proxy for Amazon SNS

In addition to exposing Lambda functions or HTTP endpoints, you can also create an API Gateway API as a proxy to an AWS service, such as Amazon SNS, Amazon S3, Amazon Kinesis, enabling your client to access the back-end AWS services through your APIs. In this walkthrough, we illustrate this by creating an API to expose Amazon SNS. For examples of integrating an API with other AWS services, see Tutorials.

An AWS service proxy can call only one action in an AWS service, and that action typically does not change. If you want more flexibility, you should call a Lambda function instead.

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

This walkthrough builds on the instructions and concepts in the Build an API to Expose a Lambda Function, which shows you how to use API Gateway to create a custom API, connect it to a set of AWS Lambda functions, and then call the Lambda functions from your API. If you have not yet completed that walkthrough, we suggest that you do it first.

Prerequisites

Before you begin this walkthrough, you should have already done the following:

  1. Complete the steps in Get Ready to Use API Gateway.

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

  3. At a minimum, open the API Gateway console and create a new API named MyDemoAPI. For more information, see Build an API Gateway API to Expose an HTTP Endpoint.

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

  5. Complete the rest of the steps in the Build an API to Expose a Lambda Function.

  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 will create a resource that will enable 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 will create a GET method that will enable 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 will create an IAM role that your AWS service proxy will use 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 will 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 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" ] } ] }

    Note

    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 New Role.

  10. For Role Name, type a name for the execution role (for example, APIGatewayAWSProxyExecRole), and then choose Next Step.

  11. Next to Amazon EC2, choose Select.

    Note

    You choose Select here because you need to choose a standard AWS service role statement before you can continue. There is currently no option to choose a standard API Gateway service role statement. Later in this step, you will modify the standard Amazon EC2 service role statement for use with API Gateway.

  12. In the list of policies, select APIGatewayAWSProxyExecPolicy, and then choose Next Step.

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

  14. Choose Create Role.

    The invocation role IAM just created enables Amazon EC2 to get a list of the Amazon SNS topics for the AWS account. You will change this role to enable API Gateway to get a list of the Amazon SNS topics for the AWS account instead.

  15. In the list of roles, select APIGatewayAWSProxyExecRole.

  16. In the Trust Relationships area, choose Edit Trust Relationship.

  17. For Policy Document, replace ec2.amazonaws.com with apigateway.amazonaws.com so that the access control policy document now looks as follows:

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

    This policy document enables API Gateway to take actions on behalf of your AWS account.

  18. Choose Update Trust Policy.

Step 4: Specify Method Settings and Test the Method

In this step, you will specify the settings for the GET method so that it can interact with an AWS service through an AWS service proxy. You will 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 will display 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 will deploy the API so that you can begin calling 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 will 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.

Caution

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, click 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 as a Lambda Proxy or Create an API as an Amazon Kinesis Proxy.