Monitor API Gateway endpoints with Amazon CloudWatch Synthetics

Monitoring the health of your API endpoints is important to understand the overall health of your workloads. You can use Amazon CloudWatch Synthetics to monitor your API endpoints and understand the overall health of your workloads. CloudWatch Synthetics canaries allow you to monitor API endpoints by creating HTTP steps and configuring the request type, endpoint URL, headers to include, and a custom request payload.

When your API is hosted using Amazon API Gateway, the process is simple. With the release of API Gateway blueprint for API canaries, you can select, from a single location, the API endpoints to monitor, the stage, the method to use, and more. For API endpoints hosted on Amazon API Gateway in a different AWS Region or AWS account, you can use an Amazon API Gateway Swagger template to configure canaries to monitor your API endpoints.

Prerequisites

To proceed with the following walkthrough of creating a canary to monitor API endpoints, you need to have an API hosted on Amazon API Gateway. If you do not have an API already created, you can use this sample API.

Creating canaries with the API Gateway blueprint

Follow these steps to monitor API endpoints hosted on Amazon API Gateway in the same AWS account as the one used to create the canaries.

1. Open the Amazon CloudWatch console and choose Canaries. The dashboard shows all the canaries that have currently been provisioned to monitor various endpoints.
2. Choose Create canary and start configuring the canary to monitor your API endpoints.

Figure 1: Canaries page

3. Although you can create canaries by uploading a script or importing one from Amazon Simple Storage Service (S3), it is much easier to use a blueprint. On Create canary, choose Use a blueprint. Under Blueprints, choose API canary. Under Canary builder, enter a name for the canary (for example, petstore-api-canary).

Figure 2: Create canary page

4. Select I’m using an Amazon API Gateway API, and then select Choose API and stage from API Gateway. I use this option because the PetStore API is hosted in the same account and Region I use to create the canary. CloudWatch Synthetics lists all the API endpoints and their stages in the current Region.

Figure 3: Using Amazon API Gateway API

5. In API, choose the PetStore API, and in Stage, choose test. Based on these selections, CloudWatch Synthetics populates the correct endpoint URL for the choice of API and stage.

Figure 4: Application or endpoint URL

Alternatively, if you provide an API Gateway Swagger template to CloudWatch Synthetics, it populates the correct endpoint URL for the API and stage based on the Swagger template.

Figure 5: Use API Gateway Swagger template

6. In HTTP request details, configure the HTTP steps that the canary uses to monitor API endpoints. The new Amazon API Gateway blueprint for creating API canaries simplifies this process. Based on the API and stage I selected in the previous step, or the Swagger template provided, it lists all the resources available for that API and stage.

Figure 6: HTTP request details

7. When I select the resource I want to send canary requests to, CloudWatch Synthetics prompts me for the inputs required to make valid requests to the API endpoint.This includes limiting me to the acceptable HTTP methods for that resource and any required parameters, such as URL query string, request headers, or request payload. The /pets resource of my API accepts both GET and POST requests, so CloudWatch Synthetics allows me to select either method.

Figure 7: /pets resource in HTTP request details

8. For the first step of the canary for the /pets resource, under Method, choose GET. Although there are no required query strings, you can select Show optional query strings to see what you can include with the request. In this case, there are two optional query strings. For the purposes of this blog, I use the name of the query string as type and its Value as cat.

Figure 8: GET method selected for /pets resource

9. To capture the response headers and body for requests made by the canary, select Capture headers and response body. This option allows you to see the headers and response body returned by the API endpoint in the CloudWatch console. Alternatively, you can view canary run data stored in the Amazon S3 bucket used with the canary.
10. For Step name, enter /pets-GET. Because I use multiple HTTP steps as part of my canary run, I also select Continue canary execution on Step Failure. This option ensures that the canary makes all the requests described by my steps even if there is a failure. This makes it easier for me to narrow down issues that my API might be experiencing. During cases where the steps in the canary are dependent on the success of any previous steps, consider not using this option so the canary execution stops if it encounters any failure. Choose Save before you add another step.

Figure 9: HTTP Request step name /pets-GET

11. Now use the POST method for the /pets When I choose POST from the list, the request data is populated based on what the API is expecting.

Figure 10: POST method selected for /pets resource

12. Enter values for the request data, and then select Capture headers and response body. In Step name, enter /pets-POST,and then select Continue canary execution on Step Failure. Choose Save before you add another step.

Figure 11: HTTP Request step name /pets-POST

13. When you choose the /pets/{petId} resource, CloudWatch Synthetics identifies that the only HTTP method accepted by this resource is GET. This prevents misconfigurations. You are prompted to enter an ID in the petId This ID is required by the API resource.

Figure 12: HTTP request details for resource /pets/{petId

14. For Method, choose GET and in petId, enter an ID to be used with the request. This resource does not need any query strings included with the request. I name this step /pets/{petId}-GETand then choose Save.

Figure 13: HTTP request details for resource petId

The script used by the canary is updated automatically based on the information you provide when you configure the HTTP requests.

Figure 14: Script editor

Restrict headers from the response

You can restrict headers from the response received if they contain sensitive information that you want to keep secure. To use this security feature, in the canary script, locate the restrictedHeaders section and include any sensitive response headers. Each configured HTTP request has its own step in the canary script, which makes it possible to customize header restriction for each request. In this case, I restrict the x-amz-apigw-id header for the /pets-GET request.

Figure 15: x-amz-apigw-id in the canary script

Other configuration parameters

CloudWatch Synthetics canaries offer other configuration parameters, such as the frequency at which to run the canaries, where and how long to retain canary data, the AWS Identity and Access Management role used, and more. In this post, I use default values for the remaining settings and then create the canary. It takes up to a minute before I start seeing the metrics for the canary.

After you have created the canary, it periodically sends requests to the API based on the configuration parameters and reports the health of the API based on the responses received. This gives you confidence in the observability and health of your API endpoints.

Figure 16: Canary runs

You can expand the steps to see the request and response. Looking at the response headers for /pets-GET and /pets-POST, I find that the value for the header x-amz-apigw-id is not logged (restricted) for /pets-GET but it is for /pets-POST. This is because I chose to restrict that header for the /pets-GET step only.

Figure 17: Request and response for /pets-GET and /pets-POST

Cleaning up

After you have finished experimenting, and to avoid ongoing charges to your account, delete the canaries you created. For instructions, check editing or deleting a Canary in the Amazon CloudWatch User Guide.

Conclusion

In this post, I showed how you can use the Amazon API Gateway blueprint for Amazon CloudWatch Synthetics to quickly and easily create canaries to monitor your Amazon API Gateway endpoints. The blueprint helps you create API canaries by using the correct configuration for the API endpoint (endpoint URL, resource, query strings, headers, and more). It also helps reduce the risk of errors or misconfigurations that could result in inaccurate reporting of the API endpoint health.

For more information, see Amazon CloudWatch Synthetics supports Amazon API Gateway in API blueprint, API canary in the Amazon CloudWatch User Guide, and Export a REST API from API Gateway in the Amazon API Gateway Developer Guide.

About the Author

Mahanth Jayadeva is a Solutions Architect at Amazon Web Services (AWS) on the AWS Well-Architected team. He works with customers and AWS Partner Network partners of all sizes to help them build secure, high-performing, resilient, and efficient infrastructure for their applications. He spends his free time playing with his pup, Cosmo, and learning more about astronomy. He is an avid gamer.