S Uma Shankar Reddy

Posted on Sep 5

Amazon API Gateway for Serverless Applications

#ai #awsbigdata

Real-time message communication with WebSocket APIs

In a WebSocket API, the client and server can send messages to each other at any time. With a WebSocket connection, your backend servers can push data to connected users and devices, avoiding the need to implement complex polling mechanisms.

For example, you could build a serverless application using an API Gateway WebSocket API and Lambda function to send and receive messages to and from users in a chat room.

Architecture demonstrating bidirectional communication between users, API Gateway, and backend APIs.

In API Gateway, you can create a WebSocket API as a stateful frontend for an AWS service, such as Lambda or Amazon DynamoDB, or for an HTTP endpoint. The WebSocket API will then invoke your correct backend service based on the content of the messages it receives from client applications.

Benefits and use cases of WebSocket APIs

API Gateway WebSocket APIs are designed for bidirectional communication between your client and backend architecture. You can do this by using any WebSockets client such as a mobile app, chat app, AWS IOT device, or application dashboard.
Benefits and use cases of WebSocket APIs

When you connect the client to API Gateway, API Gateway will manage the persistence and state needed to connect it to your clients. Unlike a REST API, which receives and responds to requests, a WebSocket API supports two-way communication between your client applications and your backend.
WebSocket APIs are often used in real-time application use cases such as:

Chat applications

Streaming dashboards

Real-time alerts and notifications

Collaboration platforms

Multiplayer games

Financial trading platforms

By using WebSockets with API Gateway, your clients can send messages to a service and the services can independently send messages back to the clients. This bidirectional behavior creates more valuable interactions between your clients and services because the services can push data to clients without requiring clients to make an explicit request.
For WebSocket APIs, the API Gateway free tier currently includes one million messages (sent or received) and 750,000 connection minutes for up to 12 months.
Developing a WebSocket API in API Gateway

As you're developing your WebSocket API in API Gateway, there are a number of characteristics you need to choose for your API. These characteristics depend on your API's use case.

For example, you might want to only allow certain clients to call your API, or you might want it to be available to everyone. In addition, you might want an API call to invoke a Lambda function, make a database query, or call an application. All of these options will change the characteristics of the API as you design and deploy it.

Creating and configuring WebSocket APIs

To create a functional API, you must have at least one route, integration, and stage before deploying the API. The creation of APIs will be discussed in more depth in later lessons, but this overview walks through the creation of specifically a WebSocket API. Select each hotspot to learn a brief overview of what you need to create an WebSocket API.

API Gateway console displaying the Create a WebSocket API dashboard.

Using WebSocket routes

With WebSocket APIs in API Gateway, JSON messages can be routed to invoke a specific backend service based on message content. When a client sends a message over its WebSocket connection, this results in a route request to the WebSocket API. The request will be matched to the route with the corresponding route key in API Gateway.

There are three predefined routes that can be used with WebSocket APIs: $connect, $disconnect, and $default. In addition to the predefined routes, you can also create custom routes. Select each hotspot to learn about the predefined routes and custom routes API Gateway WebSocket APIs offer.

After configuring the WebSocket API routes, whether predefined or custom, the next step is to attach integrations to each route.

WebSocket API integrations

After setting up an API route, you must integrate it with an endpoint in the backend. A backend endpoint is also referred to as an integration endpoint and can be a Lambda function, an HTTP endpoint, or an AWS service action. The API integration has an integration request and an integration response option.
After configuring the WebSocket API routes, whether predefined or custom, the next step is to attach integrations to each route.

WebSocket API integrations

Integration request

To set up one-way communication for your WebSocket, you will attach an integration request to your route. Setting up an integration request involves the following:

Choosing a route key to integrate to the backend. As shown earlier in this lesson, this can include a predefined route key for $connect, $disconnect, $default, or a custom route.

Specifying the backend endpoint to invoke for each of the routes you choose, such as an AWS service or HTTP endpoint.

Configuring how to transform the route request data, if necessary, into integration request data by specifying one or more request templates.

Take note of the integration types listed for WebSocket APIs integration requests. Each of these will be discussed in further detail in a later lesson.

Integration response

WebSocket routes can be configured for two-way or one-way communication. If a route has a route response, it is configured for two-way communication. Otherwise, it is configured for one-way communication.

When a route is configured for two-way communication, an integration response helps you to configure transformations on the returned message payload, similar to integration responses for REST APIs.

If a route is configured for one-way communication then, regardless of any integration response configuration, no response will be returned over the WebSocket channel after the message is processed.

Designing REST APIs
The regional endpoint is designed to reduce latency when calls are made from the same AWS Region as the API. In this model, API Gateway does not deploy its own CloudFront distribution in front of your API. Instead, traffic destined for your API will be directed straight at the API endpoint in the Region where you’ve deployed it.

This endpoint type gives you lower latency for applications that are invoking your API from within the same Region (for example, an API that is going to be accessed from EC2 instances within the same Region).

The regional endpoint provides you with the flexibility to deploy your own CloudFront distribution or content delivery network (CDN) in front of API Gateway and control that distribution using your own settings for customized scenarios. An example of this might be to design for disaster recovery scenarios or implement load balancing in a very customized way.

Edge-optimized endpoint
The edge-optimized endpoint is designed to help you reduce client latency from anywhere on the internet. If you choose an edge-optimized endpoint, API Gateway will automatically configure a fully managed CloudFront distribution to provide lower latency access to your API.

This endpoint-type setup reduces your first hit latency for your API. An additional benefit of using a managed CloudFront distribution is that you don’t have to pay for or manage a CDN separately from API Gateway.

Private endpoint
The private endpoint is designed to expose APIs only inside your selected Amazon Virtual Private Cloud (Amazon VPC). This endpoint type is still managed by API Gateway, but requests are only routable and can only originate from within a single virtual private cloud (VPC) that you control.

This endpoint type is designed for applications that have very secure workloads, such as healthcare or financial data that cannot be exposed publicly on the internet. There are no data transfer-out charges for private APIs. However, AWS PrivateLink charges apply when using private APIs in API Gateway.

Building and Deploying APIs with Amazon API Gateway

1. Anatomy of the API Call

When deploying an API in Amazon API Gateway, a base invoke URL is generated based on your deployment stage.

https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}/{resource_path}

{restapi_id}: Unique identifier generated by AWS upon API creation.
{region}: The AWS Region where the API is hosted.
{stage_name}: The deployed environment/snapshot (e.g., dev, prod).
{resource_path}: The specific resource endpoint exposed to callers.

Custom Domain Names
To make URLs user-friendly and consistent across environments, attach a custom domain name (e.g., api.example.com). API Gateway integrates directly with AWS Certificate Manager (ACM) to manage SSL/TLS certificates.

2. Steps to Build an API in the Console

Choose API Type: Select REST API, HTTP API, or WebSocket API based on workload requirements.
Create Resources: Form a hierarchical tree of addressable endpoints starting at root (/). Use {param} syntax for path parameters.
Configure Proxy Integration (Optional): Setting up a greedy path parameter {proxy+} automatically provisions an ANY HTTP method to route all sub-paths and verbs to a single backend (HTTP endpoint or AWS Lambda).
Create Methods & Select Integration Type: Define standard HTTP verbs (GET, POST, PUT, DELETE, etc.) and specify how requests map to backends:
Lambda Function: Direct invocation of serverless compute.
HTTP Endpoint: Proxying to external or legacy HTTP/HTTPS APIs.
AWS Service: Direct integration with services like Amazon S3, DynamoDB, or Kinesis without intermediary compute.
Mock: Generates API responses without sending traffic to a backend (useful for testing or CORS handling).
VPC Link: Direct access to private resources inside a VPC (e.g., Application Load Balancers or Network Load Balancers).
Test Methods: Execute method calls directly within the console to view latency, response bodies, and simulated request/response state changes.

3. API Stages & Version Management

A stage is a named reference to a deployment representing a point-in-time snapshot of the API.

Stage Configuration: Caching, throttling thresholds, and usage plans are applied per stage.
Stage Variables: Environment-specific key-value pairs referenced via $stageVariables.variableName to dynamically point integration endpoints or Lambda function aliases at runtime.
Canary Deployments: Route a controlled percentage of traffic (e.g., 10%) to a new API version within the same stage to validate changes before promoting them.

4. Deployment Best Practices

Lambda Aliases + API Stages: Pair API Gateway stages with Lambda version aliases via stage variables to decouple deployments and prevent hardcoded ARNs.
Canary Releases: Safely test API revisions with real user traffic without spinning up new domains.
Infrastructure as Code (IaC): Use AWS SAM (Serverless Application Model) or OpenAPI/Swagger specifications to automate consistent, repeatable deployments across environments.

Knowledge Check: Correct Answers

The two true statements from the check are:

[x] If you choose to configure resource as a proxy, it will automatically create a special HTTP method called ANY.
[x] Integration options include Lambda Function, HTTP Endpoint, AWS Service, Mock, and VPC Link.

(Incorrect: API Gateway URLs **can* be customized with custom domain names. Console testing performs actual executions that modify backend state, even though log output inside the console is simulated.)*
Managing API Access
Managing access to APIs

The next important step for you to consider after you have successfully designed and deployed your API is how you will manage access and authorization for the API. API Gateway provides you with multiple, customizable options for:

Authorizing an entity to access your APIs
Providing more granular control
Controlling the amount of access through throttling
Before discussing these different use cases, you need to understand the different options for authenticating and authorizing your APIs in API Gateway.

Authorization and authentication comparison

Each of these, authorization and authentication, have advantages that should be matched to both your application needs and your organizational standards. This table shows a comparison of authorization and authentication options and features that they are compatible with.

Pay based on your monthly active users
Authorization for API Gateway

As shown in the comparison table, there are three main ways to authorize API calls to your API Gateway endpoints:

1
Use IAM and Signature version 4 (also known as Sig v4) to authenticate and authorize entities to access your APIs.

2
Use Lambda Authorizers, which you can use to support bearer token authentication strategies such as OAuth or SAML.

3
Use Amazon Cognito with user pools.

Each of the authorizing options has advantages that should be matched to your application needs and organizational standards. For example, you need to consider who consumes the API. If it’s external developers, you probably want to consider using Lambda Authorizers or Cognito.

Authorizing with IAM

If you have an internal service or a restricted number of customers, IAM is a great choice for authorization, especially for applications that use IAM to interact with other AWS services using IAM roles. To learn more about the signing process, select each hotspot.

API Gateway architecture illustrating Sig v4 credentials used for IAM authorization.

Lambda Authorizers

You also need to consider what you already have in place that should be used. If you are using an OAuth strategy as an organization, you may want to consider Lambda Authorizer. To learn more about Lambda Authorizers, select each hotspot.

API Gateway architecture highlighting a Lambda function performing authorization and an optional Policy cache.

To make it easy to get started with this method, you can choose the API Gateway Lambda Authorizer blueprint when creating your authorizer function from the Lambda console.

Lambda function console creation using API Gateway Lambda Authorizer blueprint to create the Lambda Authorizer.
To summarize, a Lambda Authorizer is simply a Lambda function that you can write to perform any custom authorization that you need. There are two types of Lambda Authorizers you should be aware of: Token and Request.

Lambda Authorizer token types

For token-type Lambda Authorizers, API Gateway passes the source token to the Lambda function as a JSON input. Based on the value of this token, your Lambda function will determine whether to allow the request.

To learn more about Lambda Authorizer tokens, select each hotspot.

Diagram highlighting the flow of token information through HTTP header to Lambda Authorizer.

Lambda Authorizer request types

Request-type Lambda Authorizers are useful if you need more information about the request itself before authorizing it.

To learn more about Lambda Authorizer requests, select each hotspot.

Diagram highlighting the flow of header information in request-type Lambda Authorizer.

Cognito Authorizers

As an alternative to using IAM or Lambda authorizers, you can use Amazon Cognito and a Cognito User Pool to control access to your APIs.

To learn more about Cognito Authorizers, select each hotspot.

API Gateway architecture highlighting the use of Cognito and OIDC tokens for authorization.

In the following section, match the authorizer in the column on the left with the correct description on the right.

If you're using the keyboard to navigate, TAB to the term on the left, press the SPACE BAR, then use the right arrow key to move to the column on the right. Press the SPACE BAR to match, then repeat for the next item. Press ENTER to submit.

Lambda Authorizer
Selectable item

Cognito Authorizer
Selectable item

IAM Authorizer
Selectable item

All requests are required to be signed using AWS Sig v4.
Selectable item

Amazon API Gateway supplies an authorization token to a Lambda function.
Selectable item

After a user is authenticated against the user pool, they obtain an OIDC token.
Selectable item
SUBMIT

Throttling and usage plans

Beyond just allowing or denying access to your APIs, API Gateway also helps you manage the volume of API calls that are processed through your API endpoint.

With API Gateway, you can set throttle and quota limits on your API consumers. This can useful for things such as preventing one consumer from using all of your backend system’s capacity or to ensure that your downstream systems can manage the number of requests you send through.

Keys on a key ring
API keys

With API Gateway, you can create and distribute API keys to your customers, which can be used to identify the consumer and apply desired usage and throttle limits to their requests. Customers include the API key through x-API-key header in requests.

Usage plans

You can use API keys with usage plans to set up some very specific plans that make sense for your use case. For example, you can perform API key throttling based on a rate and a burst per API key. API key usage can also be used to meter daily, weekly, and monthly usage.

You can set throttle and quota limits based on API keys through the usage plans feature. You can set up usage plans for:

API Key Throttling per second and burst
API Key Quota by day, week, or month
API Key Usage by daily usage records
Example of usage plans based on types of consumers

Using the information on API keys and usage plans, review this throttling example where you might throttle with usage plans for specific types of consumers.

To learn more, select each hotspot.

Diagram showing traffic from mobile apps, web sites, and services flowing to API Gateway. Mobile apps and services have a throttling limit called out.

With usage plans, you can create both the throttle rate limit and apply a daily quota.

Token bucket algorithm

Leaky bucket illustration highlighting flow of requests for throttling.
Burst: Maximum size of bucket
Rate: Number of tokens (requests) added to bucket
The method by which the limits are measured and throttled is based on the token bucket algorithm, which is a widely used algorithm for checking that network traffic conforms to set limits. A token, in this case, counts as a request and the burst is the maximum bucket size.

Requests that come into the bucket are fulfilled at a steady rate. If the rate at which the bucket is being filled causes the bucket to fill up and exceed the burst value, a 429 Too Many Requests error would be returned.

API Gateway sets a limit on a steady-state rate and a burst of request submissions per account and per Region. At the account level, by default, API Gateway limits the steady-state request rate to 10,000 requests per second. It limits the burst to 5,000 requests across all APIs within an AWS account. However, as discussed earlier, you can use usage plans to manage limits at a more granular level.

Throttling settings hierarchy

The type and level of throttling applied to a request is dependent on all of the limits involved and are applied in this order:

Per-client, per-method throttling limits that you set for an API stage in a usage plan
Per-client throttling limits that you set in a usage plan
Default per-method limits and individual per-method limits that you set in API stage settings
The account level limit
Which of the following statements are true? (Select THREE.) Select the correct answers and choose SUBMIT.

If you're using the keyboard to navigate, press TAB to navigate to the correct answer and press the SPACE BAR to select. Repeat these steps until all correct responses are checked, then press ENTER to submit.

You can throttle APIs with usage plans.

You cannot override the default stage level throttling.

The method by which limits are measured and throttled is based on the token bucket algorithm.

All consumers of an API must share the same quotas.

You can override default stage level throttling.

You cannot apply daily quotas to APIs with usage plans.

SUBMIT

IAM permissions

You learned how IAM policies are used as part of the authorization models as an earlier part of this lesson. Now, it's time to take a look at the types of permission controls you can implement using IAM policies. There are two types of IAM permissions for APIs:

Telephone
Multipurpose pocket knife tool
When it comes to granting access to your APIs, you need to think about two types of permissions:

1
Who can invoke the API: To call a deployed API, or refresh the API caching, the caller needs the execute-api permission.

2
Who can manage the API: To create, deploy, and manage an API in API Gateway, the API developer needs the apigateway permission.

Invoke permissions

For the execute-api permission, you need to create IAM policies that permit a specified API caller to invoke the desired API method. To apply this IAM policy on the API method, you need to configure the API method to use an authorization type of AWS_IAM.

This example grants "Allow" Invoke permissions on the POST method of mydemoresource API.

Screenshot of policy showing invoke permission.
When you do this, API Gateway will expect an IAM Sig v4 request for any requests that come to that API method. After you have associated this authorization type with your API method, you can then allow users with this permission to invoke your API. This could be an IAM user who represents an API caller; it could be an IAM group containing a set of IAM users; or it could be an IAM role assumed by a user, an EC2 instance, or an application running inside AWS.

For the execute-api permission, create IAM policies that permit a specified API caller to invoke the desired API method.

Manage permissions

To allow an API developer to create and manage an API in API Gateway, you need IAM permission policies that allow a specified API developer to create, update, deploy, view, or delete required API entities. To do that, create a policy using the apigateway:HTTP_VERB format, associated with the specific resource using the verb that you want to permit or deny in the policy.

Screenshot of policy showing apigateway permission.
In this example, the user with this policy is limited to perform the GET method requests on one of the API resources, but is permitted to take all of the actions (*) on the second resource.

To learn more about managing permission examples, see Amazon API Gateway identity-based policy examples(opens in a new tab).

Resource policies

Resource policies help you to further refine access for your APIs. While an IAM policy is used to grant permission to a user, group, or role, you can also apply policies directly on API Gateway using a resource policy. A resource policy is a JSON policy document that you attach to an API to limit access by users from a specified account, IP address range, VPC, or VPC endpoint. You can make this as granular as you need, and resource policies can be used in coordination with IAM policies to restrict access.

For example, you could use resource policies to provide access to another AWS account, or to limit access to your API from a particular set of IP address ranges. You can also use resource policies to grant access to specific VPCs or VPC endpoints.

For a full list of the conditions you can use within your resource policies, see Controlling access to an API with API Gateway resource policies(opens in a new tab) in the Amazon API Gateway Developer Guide.

Now that you understand the basics of resource policies for API Gateway, these examples show how you can limit access for users, IP addresses, and by VPC.

Screenshot of a resource policy showing permission by account for specific actions.
Limiting access by user example

In this example, the resource policy allows a user from another AWS account (account-id:user/George) to perform GET requests on the pets resource of our API.

Limiting by IP address example

This resource policy denies any user with a source IP address in one of two specified ranges from accessing the API.

This is done by specifying an effect of DENY and an IpAddress condition with an array of source IP addresses.

Screenshot of a resource policy that denies users who aren't within a given IP address range.
Screenshot of a resource policy that denies anyone coming from a specific VPC ID.
Limiting by VPC example

This resource policy denies anyone (indicated by the principal = *) who is NOT coming from the VPC specified as the sourceVpc within the Condition.

Since the Principal in the policy is set to "*", other authorization types can be used alongside the resource policy. However, if the Principal is set to "AWS," authorization will fail for all resources not secured with AWS_IAM authorization, including unsecured resources.

Resource policies and authentication methods

Resource policy and authentication methods work together to grant access to your APIs. As illustrated below, methods for securing your APIs work in aggregate. To learn more, expand each of the following four categories.

API Gateway resource policy only

Lambda Authorizer and resource policy

IAM authentication and resource policy

Cognito authentication and resource policy
To see flow charts and tables to help you sort through your specific use case, see How API Gateway resource policies affect authorization workflow(opens in a new tab) in the Amazon API Gateway Developer Guide.

Which of the following statements are true? (Select THREE.) Select the correct answers and choose SUBMIT.

You must choose between using resource policies or configuring an authorizer to secure an API.

You can grant permission to invoke an API with execute-api.

You can grant permission to manage an API with
apigateway.

Resource policies can restrict access by account.

You can grant permission to manage an API with
execute-api.
CloudWatch Metrics for API Gateway

After your APIs are deployed, you can use CloudWatch Metrics to monitor performance of deployed APIs. API Gateway has seven default metrics out of the box:

•
Count: Total number of API requests in a period

•
Latency: Time between when API Gateway receives a request from a client and when it returns a response to the client; this includes the integration latency and other API Gateway overhead

•
IntegrationLatency: Time between when API Gateway relays a request to the backend and when it receives a response from the backend

•
4xxError: Client-side errors captured in a specified period

•
5xxError: Server-side errors captured in a specified period

•
CacheHitCount: Number of requests served from the API cache in a given period

•
CacheMissCount: Number of requests served from the backend in a given period, when API caching is turned on

With these metrics, you can monitor details such as the following:

•
How often your APIs are being called

•
The number of invocations to your API

•
The latency of the API responses

•
If there are any errors, and if so, whether they are 400 errors or 500 errors

•
Whether your cache is being hit or how many times the backend needed to be called while caching was enabled

In addition, consider the value of turning on detailed metrics so you can see these metrics at the method level. This is where you would be able to see details about gets, posts, deletes, and so on.

You can turn on detailed metrics from the Stage settings.

Calculating API Gateway overhead

Two key metrics that are used to calculate the API Gateway overhead of deployed APIs are the Latency and IntegrationLatency CloudWatch Metrics.

1
The latency metric gives you details about how long it takes for a full round-trip response, from the second your customer invokes your API to when your API responds with the results. This is a full round-trip duration of an API request through API Gateway.

2
Integration latency is how long it takes for API Gateway to make the invocation to your backend and receive the response.

The difference between these two metrics gives you your API Gateway overhead. Together, these metrics can help you fine-tune your applications and see where the bottlenecks are.

CloudWatch Logs for API Gateway

In addition to CloudWatch Metrics, you can also learn a lot about how your APIs are performing from CloudWatch Logs. API Gateway has two types of CloudWatch logs built in. To learn about a category, choose the appropriate tab.

Execution Logging

Access Logging
The first type is execution logging, which logs what’s happening on the roundtrip of a request. You can see all the details from when the request was made, the other request parameters, everything that happened between the requests, and what happened when API Gateway returned the results to the client that’s calling the service.

Execution logs can be useful to troubleshoot APIs, but can result in logging sensitive data. Because of this, it is recommended you don't enable Log full requests/responses data for production APIs. In addition, there is a cost component associated with logging your APIs.

API Gateway console page showing where you can implement execution logging from the stages page.
Access logging is fully customizable using JSON formatting. If you need to, you can publish them to a third-party resource to help you analyze them.

Troubleshooting Exercise – Execution Logs
To experience these monitoring and troubleshooting tools in action, this scenario outlines a situation where your customers are reporting errors while trying to use the FAQ API. You bring up the dashboard for the API being called, and notice a spike in 4xx errors around the time of the reports. Continue through the steps to learn more about the errors your customers are experiencing, then diagnose the root cause of this issue.

Lambda dashboard showing some 400 errors.
Step 1
Review the metric in CloudWatch
Hover over the data for more details including the time associated with the error spike. Choose Logs for the details of logs for that time frame.

Screenshot of CloudWatch metric for 400 errors with mouse hovering over spike in graph to get date and time details.
Step 2
Open the execution log
Pick the execution log associated with the API. The log name has the API ID and the stage name in its name. In this example, it's the last one on the list.

Screenshot of list of logs available highlighting the one named to match the API.
Step 3
Look for errors in the log
There are 2 error lines: one that mentions throttle limit exceeded and one that indicates a 429 error.

Screenshot of the execution log showing error that key throttle limit was exceeded on httpMethod GET Limit:1 Burst:5.
Step 4
Check potential throttling settings
Because the error indicated throttling, the next step would be to check how throttling is applied to this API and method. Review the next four slides to decide which setting is generating the error.

Setting 1
Usage plan: API Key Throttling
Screenshot of API GET method showing that there is no API key in use for this method.
Setting 2
Method throttling at stage level
Screenshot of stage editor for method showing choice to override for method and throttling settings of rate = 1 burst = 5.
Setting 3
Stage level defaults
Screenshot of stage editor for this API showing the default method throttling set for a rate of 50 and a burst of 75.
Setting 4
Account Limits
Screenshot of Account Settings text that indicates that your current account level throttling rate is 1000 requests per second with a burst of 5,000 requests.
Which of these appears to be the root cause in the troubleshooting scenario? Select the correct answer and choose SUBMIT.

If you're using the keyboard to navigate, press TAB to navigate to the correct answer, press the SPACE BAR to select, and press ENTER to submit.

API Key throttling on the method

Throttling on the method at the stage level

Default throttling limits on the stage

Account level limits

SUBMIT

Monitoring with X-Ray and CloudTrail

There are two AWS tools you should understand to analyze your API use and performance: AWS X-Ray and AWS CloudTrail.

The AWS X-Ray service icon.
(opens in a new tab)

AWS X-Ray

You can use X-Ray to trace and analyze user requests as they travel through your Amazon API Gateway APIs to the underlying services. With X-Ray, you can understand how your application is performing to identify and troubleshoot the root cause of performance issues and errors. X-Ray gives you an end-to-end view of an entire request, so you can analyze latencies and errors in your APIs and their backend services. You can also configure sampling rules to tell X-Ray which requests to record, and at what sampling rates, according to criteria that you specify.

To summarize, with X-Ray, you can trace and analyze requests as they travel through your APIs to services:

Analyze latencies and debug errors in your APIs and their backend services.
Configure sampling rules to focus on specific requests.
AWS CloudTrail

The second service, CloudTrail, captures all API calls for API Gateway as events, including calls from the API Gateway console and from code calls to your API Gateway APIs.

Using the information collected by CloudTrail, you can determine the request that was made to API Gateway, the IP address from which the request was made, who made the request, when it was made, and additional details. You can view the most recent events in the CloudTrail console in Event history.

To summarize, CloudTrail captures all API calls for API Gateway as events.

IP address, requester, and time of request are included.
Event history can be reviewed.
Create a trail to send events to an Amazon Simple Storage Service (Amazon S3) bucket.
The AWS CloudTrail service icon.
(opens in a new tab)

X-Ray trace examples

These examples reflect an AWS X-Ray trace for a GET method request for the FAQ-API on the Demo stage. The GET method for this API is configured with a proxy integration to Lambda. When the GET request is received, Lambda invokes the FAQ Lambda function.

This first example demonstrates API Gateway Latency metrics for a Lambda cold start. To learn more about the sections of the X-Ray trace, select each hotspot.

Screenshot of X-Ray trace for API call to Lambda function behind API Gateway.

Diving deeper into the example, this image shows a deeper look at the Lambda portion of this trace. To learn more about this example, choose the right arrow to move to the next image and the left arrow to move to the previous image. To use the zoom feature, choose the zoom image button.

1 of 3

As shown, the entire duration for the Lambda cold start is 232 ms, with a billable duration of 26 ms.

Next, this example demonstrates the API Gateway Latency metrics for a Lambda warm start. To learn more about the sections of the X-Ray trace, select each hotspot.

X-Ray trace showing API Gateway integrated with Lambda function with a warm start.

1 of 3

As shown, the entire duration for the Lambda warm start is 18 ms, with a billable duration of 1 ms. Compared to the metrics from the Lambda cold start, the warm start steeply decreases the duration that the Lambda function must run.

Troubleshooting Exercise – Access Logs and X-Ray
To experience these monitoring and troubleshooting tools in action, this scenario outlines a situation where a single customer reports getting an access denied error trying to call the API between 9:45 and 10 am. The IP address of the reporter was 207.172.87.12. Continue through the steps to look at two ways to troubleshoot this report.

Step 1
Review errors with access logs
Check the name of the CloudWatch Group for access logging on this API stage.

Screenshot of setting up access logging on the API stage.
Step 2
Open the access log in CloudWatch
Select the access log for this API stage.

Screenshot of selecting the access log from within CloudWatch.
Step 3
Select a log event for the time frame
There are log events for 9:48 - 9:52, so let’s review the detail on one of those.

Screenshot of Select log events for the time period.
Step 4
Review errors
In the details of this log event, you can see a successful connection (200 status) from one IP address but a 403 error for the attempt to access from 207.172.87.12.

Screenshot showing a 403 error associated with IP address 207.172.187.12.
Step 5
Review errors with X-Ray
Alternatively, you could look at the X-Ray trace for this event. Open X-Ray, select Traces, and set the Group by to ClientIP.

Screenshot of selecting Traces and setting the Group by to ClientIP.
Step 6
Select Trace
Select one of the available traces from the list.

Screenshot of selecting an available trace from the list.
Step 7
Review error reported in trace
You can quickly see there was an error on this request. If you hover over the error icon, you can see explicit details indicating that the user is not authorized to perform execute-api:invoke on the resource due to an explicit deny.

Screenshot of error indicating that the user is not authorized to perform execute-api:invoke on the resource due to an explicit deny.
What might be the cause?
Consider a few configuration options to determine the root cause of this permission error.

Option 1
Authorization settings
Screenshot of Authorization settings showing no authorization method is selected.
Option 2
Resource policy
Screenshot of Resource Policy that includes the IP address in question with explicit deny.
What appears to be the root cause in the troubleshooting scenario? Select the correct answer and choose SUBMIT.

If you're using the keyboard to navigate, press TAB to navigate to the correct answer, press the SPACE BAR to select, and press ENTER to submit.

The user lacks the IAM policy required.

Lambda Authorizer requires a token that has not been provided.

The resource policy associated with this API prevents access.

Data Mapping and Request Validation in API Gateway

API Gateway allows you to validate incoming data, transform payloads, and standardize error structures before requests ever hit your backend compute or services.

1. Data Transformations with Mapping Templates

When client request schemas and backend integration interfaces differ (e.g., a client sending/expecting JSON while a legacy SOAP backend requires XML), API Gateway handles the transformation using Velocity Template Language (VTL) mapping templates.

Integration Request Mapping: Transforms the client’s request payload, query parameters, or headers before passing them to the backend integration.
Integration Response Mapping: Transforms the backend response before returning it as the final Method Response to the client.

Key VTL Variables

Variable	Core Utility
`$input`	Accesses request data via methods like `$input.body`, `$input.json('$.path')`, `$input.params()`, and `$input.path('$.element')`.
`$stageVariables`	Retrieves stage-specific environment variables (e.g., `$stageVariables.endpointUrl`).
`$util`	Provides string and encoding utilities: `escapeJavaScript()`, `parseJson()`, `urlEncode()`, `urlDecode()`, `base64Encode()`, and `base64Decode()`.

2. Offloading Request Validation

Performing basic structural checks at the gateway layer prevents unnecessary downstream invocations (saving compute costs and reducing backend load).

Validation Checks:
Parameters: Verifies that required headers, query string parameters, or path variables exist and are non-empty.
Body Models: Uses JSON Schema Draft 4 definitions to validate the payload structure, data types, required fields, and allowed enum values (e.g., enforcing make must be "Tesla" or "Hyundai").
Early Rejection: If validation fails, API Gateway drops the call and returns an immediate 400 Bad Request without hitting downstream resources.

3. Customizing Gateway Responses

When a request is blocked or fails at the perimeter (e.g., invalid auth, throttled request, validation failure), API Gateway generates a Gateway Response directly.

You can customize Gateway Responses to adhere to organizational API standards:

Modify the HTTP status code (e.g., converting a raw 403 to a standardized response).
Inject CORS or custom security headers.
Redefine the error payload body structure (JSON/XML) for standard error types like DEFAULT_4XX, DEFAULT_5XX, RESOURCE_NOT_FOUND, or UNAUTHORIZED.

DEV Community