Amazon CloudSearch
Developer Guide (API Version 2013-01-01)

Integrating Amazon CloudSearch with API Gateway

This chapter provides information about integrating Amazon CloudSearch with Amazon API Gateway. API Gateway lets you create and host REST APIs that make calls to other services. Some use cases for using API Gateway with Amazon CloudSearch include the following:

  • Further securing the Amazon CloudSearch search endpoint using API keys or Amazon Cognito user pools

  • Using CloudWatch to monitor and log search calls to the Amazon CloudSearch domain

  • Restricting users to a more limited subset of the Amazon CloudSearch API

  • Enforcing a rate limit on the number of requests

To learn more about the benefits of API Gateway, see the API Gateway Developer Guide.


Before you integrate Amazon CloudSearch with API Gateway, you must have the following resources.

Prerequisite Description
Amazon CloudSearch Domain

For testing purposes, the domain should have some searchable data. The IMDb movies data is an excellent option.

The domain must have the following access policy:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:role/my-api-gateway-role" }, "Action": [ "cloudsearch:search", "cloudsearch:suggest" ] } ] }

This policy configures the Amazon CloudSearch domain so that only API Gateway (and probably the account owner) can access it. To learn more, see Creating an Amazon CloudSearch Domain and Configuring Access for Amazon CloudSearch.


If you want to limit the account owner's access, see Best Practices for Managing AWS Access Keys in the AWS General Reference.

IAM Role

This role delegates permissions to API Gateway and allows it to make requests to Amazon CloudSearch. The role is referred to as my-api-gateway-role within this chapter and must have the following permissions:

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:PutLogEvents", "logs:GetLogEvents", "logs:FilterLogEvents" ], "Resource": "*" }] }

The role must also have the following trust relationship:

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

To learn more, see Creating Roles in the IAM User Guide.

Creating and Configuring an API (Console)

The steps involved in creating an API vary depending on whether the request uses parameters, requires a request body, needs specific headers, and many other factors. The following procedure creates an API that has one function: performing searches on an Amazon CloudSearch domain. For more complete information about configuring APIs, see Creating an API in Amazon API Gateway.

To create an API (console)

  1. Go to, and then choose Sign In to the Console.

  2. Under Networking & Content Delivery, choose API Gateway.

  3. Choose Create API.

    Alternatively, choose Get Started if this is your first time using API Gateway.

  4. Choose New API, name the API, type an optional description, choose an Endpoint Type of Regional, and then choose Create API.

  5. Choose Actions, and then choose Create Method. From the dropdown menu, choose GET and confirm.

  6. For Integration type, choose AWS Service.

  7. For AWS Region, choose the region in which your Amazon CloudSearch domain resides.

  8. For AWS Service, choose CloudSearch.

  9. For AWS Subdomain, specify the subdomain for your Amazon CloudSearch domain's search endpoint.

    For example, if your domain's search endpoint is, specify search-my-test-asdf5ambgebbgmmodhhq5asdfg.

  10. For HTTP Method, choose GET.

  11. For Action Type, choose Use path override and specify /2013-01-01/search.

  12. For Execution role, specify the ARN for my-api-gateway-role, such as arn:aws:iam::123456789012:role/my-api-gateway-role.

  13. For Content Handling, choose Passthrough, use the default timeout, and then choose Save.

  14. Select the new method, and then choose Method Request.

  15. For URL Query String Parameters, choose Add query string, name the string q, mark it as required, and then confirm.

  16. For Request Validator, choose Validate query string parameters and headers, and then confirm.

  17. Choose Method Execution to return to the method summary.

  18. Choose Integration Request.

  19. For URL Query String Parameters, choose Add query string, name the string q, provide a mapping of method.request.querystring.q, and then confirm.

Testing the API (Console)

At this point, you've created an API that has one method. Before deploying the API, you should test it.

To test the API (console)

  1. Navigate to the Method Execution page.

  2. Choose Test.

  3. For the q field, enter a query string that will match some data in the Amazon CloudSearch domain. If you are using the IMDb movie data, try thor.

  4. Choose Test.

  5. Verify that the response body contains search results, such as the following:

    { "status": { "rid": "rcWTo8IsviEK+own", "time-ms": 1 }, "hits": { "found": 7, "start": 0, "hit": [ { "id": "tt0800369", "fields": { "rating": "7.0", "genres": [ "Action", "Adventure", "Fantasy" ], "title": "Thor", "release_date": "2011-04-21T00:00:00Z", "plot": "The powerful but arrogant god Thor is cast out of Asgard to live amongst humans in Midgard (Earth), where he soon becomes one of their finest defenders.", "rank": "135", "running_time_secs": "6900", "directors": [ "Kenneth Branagh", "Joss Whedon" ], "image_url": "", "year": "2011", "actors": [ "Chris Hemsworth", "Anthony Hopkins", "Natalie Portman" ] } }, ... ] } }

At this point, you have a functional API. You can add methods to enable more robust search requests, deploy the API and configure rate limiting, create and require the use of API keys, add Amazon Cognito user pool authentication, and much more. For more information, see the API Gateway Developer Guide.