# Integrate Amazon API Gateway with Amazon SQS to handle asynchronous REST APIs *Natalia Colantonio Favero and Gustavo Martim, Amazon Web Services* ## Summary When you deploy REST APIs, sometimes you need to expose a message queue that client applications can publish. For example, you might have problems with the latency of third-party APIs and delays in responses, or you might want to avoid the response time of database queries or avoid scaling the server when there are a large number of concurrent APIs. In these scenarios, the client applications that publish to the queue only need to know that the API received the data—not what happens after the data was received. This pattern creates a REST API endpoint by using [Amazon API Gateway](https://aws.amazon.com/api-gateway/) to send a message to [Amazon Simple Queue Service (Amazon SQS)](https://aws.amazon.com/sqs/). It creates an easy-to-implement integration between the two services that avoids direct access to the SQS queue. ## Prerequisites and limitations + An [active AWS account](https://portal.aws.amazon.com/billing/signup/iam) ## Architecture ![Architecture for integrating API Gateway with Amazon SQS](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/images/pattern-img/70984dee-e49f-4446-9d52-49ce826c3909/images/737ba0b2-da8f-4478-8c54-0a4835fd69f9.png) The diagram illustrates these steps: 1. Request a POST REST API endpoint by using a tool such as Postman, another API, or other technologies. 1. API Gateway posts a message, which is received on the request's body, on the queue. 1. Amazon SQS receives the message and sends an answer to API Gateway with a success or failure code. ## Tools + [Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) helps you create, publish, maintain, monitor, and secure REST, HTTP, and WebSocket APIs at any scale. + [AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) helps you securely manage access to your AWS resources by controlling who is authenticated and authorized to use them. + [Amazon Simple Queue Service (Amazon SQS)](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html) provides a secure, durable, and available hosted queue that helps you integrate and decouple distributed software systems and components. ## Epics ### Create an SQS queue | Task | Description | Skills required | | --- | --- | --- | | Create a queue. | To create an SQS queue that receives the messages from the REST API:1. Sign in to your [AWS account](https://portal.aws.amazon.com/billing/signup/iam).
2. Open the Amazon SQS console at [https://console.aws.amazon.com/sqs/](https://console.aws.amazon.com/sqs/).
3. Choose **Create queue**.
4. On the **Create queue** page, choose the correct AWS Region from the **Region** dropdown list.
5. For **Type**, keep the default setting (**Standard**).
6. Enter a **Name** for your queue.
7. Keep the default values for all other settings.
8. Choose **Create queue**. | App developer | ### Provide access to Amazon SQS | Task | Description | Skills required | | --- | --- | --- | | Create an IAM role. | This IAM role gives API Gateway resources full access to Amazon SQS.1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
2. In the navigation pane, choose **Roles**, **Create role**.
3. For **Trusted entity type**, choose **AWS service**.
4. For **Use case**, choose **API Gateway** from the dropdown list, and then choose **Next**, **Next**.
5. For **Role name**, enter **AWSGatewayRoleForSQS** and an optional description, and then choose **Create role**.
6. In the **Roles **pane, search for **AWSGatewayRoleForSQS**, and select its checkbox.
7. In the **Permissions policies** section, choose **Add permissions**,** Attach policies**.
8. Search for **AmazonSQSFullAccess **and select it.
9. Choose **Add permissions**.
10. In the **Summary **section of **AWSGatewayRoleForSQS**, copy the Amazon Resource Number (ARN). You will use this ID in a later step. | App developer, AWS administrator | ### Create a REST API | Task | Description | Skills required | | --- | --- | --- | | Create a REST API. | This is the REST API that HTTP requests are sent to.1. Open the API Gateway console at [https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/).
2. In the **REST API** section, choose **Build.**
3. For **API name**, enter a name and an optional description for your API, keep all other default settings, and then choose **Create API**. | App developer | | Connect API Gateway to Amazon SQS. | This step enables the message to flow from inside the HTTP request’s body to Amazon SQS.1. On the [API Gateway console](https://console.aws.amazon.com/apigateway/), choose the API that you created.
2. On the **Resources **page, in the **Methods **section, choose **Create method**.
3. For **Method type**, choose **POST**.
4. For **Integration type**, choose **AWS service**.
5. For **AWS Region**, choose the Region where you created your SQS queue.
6. For **AWS service**, choose **Simple Queue Service (SQS)**.
7. For HTTP method, choose **POST**.
8. For **Action type**, choose **Use path override**.
9. For **Path override**, enter **/**.
10. For **Execution role**, paste the ARN of the role that you created earlier.
11. Choose **Create method**. | App developer | ### Test the REST API | Task | Description | Skills required | | --- | --- | --- | | Test the REST API. | Run a test to check for missing configuration:1. On the [API Gateway console](https://console.aws.amazon.com/apigateway/), choose the REST API that you created.
2. In the **Resources **pane, choose the **POST **method.
3. Choose the **Test** tab. (Use the right arrow if the tab isn't displayed.)
4. For **Request body**, paste the following JSON code:

{
     "message": "lorem ipsum"
}

5. Choose** Test**.
You will receive an error that's similar to the following:

| App developer | | Change the API integration to forward the request properly to Amazon SQS. | Complete the configuration to fix the integration error:1. On the [API Gateway console](https://console.aws.amazon.com/apigateway/), choose the API you created, and then choose **POST**.
2. The **Method Execution** section shows the visual mapping between API Gateway and Amazon SQS. From this section, choose **Integration request**, and then choose **Edit**.
3. Expand the **HTTP headers** section, and then choose the **Add request header** parameter.For **Name**, specify **Content-Type**.For **Mapped from**, enter** 'application/x-www-form-urlencoded'**. Make sure to include the single quotation marks.Select the **Caching** checkbox.
4. Expand the **Mapping templates** section.Choose **Add mapping template**.For **Content type**, enter **application/json**.For **Template body**, paste this code:

Action=SendMessage&MessageBody=$input.body

Choose **Save**. | App developer | | Test and validate the message in Amazon SQS. | Run a test to confirm that the test completed successfully:1. On the [API Gateway console](https://console.aws.amazon.com/apigateway/), choose the REST API you created.
2. In the **Resources** pane, choose the **POST** method.
3. Choose the **Test** tab. (Use the right arrow if the tab isn't displayed.)
4. For **Request body**, paste the following JSON code:

{
     "message": "lorem ipsum"
}

5. Choose** Test**.
6. Open the [Amazon SQS console](https://console.aws.amazon.com/sqs/).
7. In the navigation pane, choose **Queues**, and then choose your queue.
8. Choose **Send and receive messages**.
9. Choose **Poll for messages**.
10. Choose **Message**. It should display the following:

Body { "message": "lorem ipsum" }

| App developer | | Test API Gateway with a special character. | Run a test that includes special characters (such as &) that aren't acceptable in a message:1. On the [API Gateway console](https://console.aws.amazon.com/apigateway/), choose your API.
2. Repeat the test from the earlier step by using the following JSON code:

{
     "message": "lorem ipsum &"
}

3. Choose** Test**.
You will receive an error such as the following:

{
  "Error": {
    "Code": "AccessDenied",
    "Message": "Access to the resource https://sqs.us-east-2.amazonaws.com/976166761794/Apg2 is denied.",
    "Type": "Sender"
  },
  "RequestId": "e83c9c67-bcf6-5e9a-91e9-c737094b17ab"
}

This is because special characters aren't supported by default in the message body. In the next step, you'll configure API Gateway to support special characters. For more information about content type conversions, see the [API Gateway documentation](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-payload-encodings-workflow.html). | App developer | | Change the API configuration to support special characters. | Adjust the configuration to accept special characters in the message:1. On the [API Gateway console](https://console.aws.amazon.com/apigateway), choose the API you created, and then choose **POST**.
2. Choose **Integration request**, and then choose **Edit**.
3. Change **Content Handling** to **Convert to text.**
4. In the **Mapping templates** section:For **Content type**, enter **application/json**.For **Template body**, specify:

Action=SendMessage&MessageBody=$util.urlEncode($input.body)

Choose **Save**.
5. Choose the **Test **tab.
6. For **Request body**, enter the JSON code from earlier:

{
     " message": "lorem ipsum &" }

7. Choose **Test**.
8. Open the [Amazon SQS console](https://console.aws.amazon.com/sqs/).
9. Select your queue, and then choose **Send and receive messages**, **Poll for messages**, **Message **as earlier.
The new message should include the special character. | App developer | ### Deploy the REST API | Task | Description | Skills required | | --- | --- | --- | | Deploy the API. |
To deploy the REST API:1. Open the [API Gateway console](https://console.aws.amazon.com/apigateway/).
2. Choose your API.
3. Choose **Deploy API**. For more information about this step, see the [API Gateway documentation](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-deploy-api-with-console.html). | App developer | | Test with an external tool. | Run a test with an external tool to confirm that the message is received successfully:1. Open a tool such as Postman, Insomnia, or cURL.
2. Run your API.
3. Open the [Amazon SQS console](https://console.aws.amazon.com/sqs/).
4. Select your queue.
5. Load messages to see the new message. | App developer | ### Clean Up | Task | Description | Skills required | | --- | --- | --- | | Delete the API. | On the [API Gateway console](https://console.aws.amazon.com/apigateway/), choose the API you created, and then choose **Delete**. | App developer | | Delete the IAM role. | On the [IAM console](https://console.aws.amazon.com/iam/), in the **Roles** pane, select **AWSGatewayRoleForSQS**, and then choose **Delete**. | App developer | | Delete the SQS queue. | On the [Amazon SQS console](https://console.aws.amazon.com/sqs/), in the **Queues** pane, choose the SQS queue you created, and then choose **Delete**. | App developer | ## Related resources + [SQS-SendMessage](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-aws-services-reference.html#SQS-SendMessage) (API Gateway documentation) + [Content type conversions in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-payload-encodings-workflow.html) (API Gateway documentation) + [$util variables](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#util-template-reference) (API Gateway documentation) + [How do I integrate an API Gateway REST API with Amazon SQS and resolve common errors?](https://repost.aws/knowledge-center/api-gateway-rest-api-sqs-errors) (AWS re:Post article)