Topic lessonTopic: Lambda and API Gateway: inputs, testing and failure investigation
API Gateway for beginners: HTTP APIs, Lambda and authorization
Amazon API Gateway accepts API requests from applications and connects them to configured backends. Lambda runs application code; API Gateway handles request routing, configured access controls and the HTTP response exchange. Follow a request for one report from the API endpoint to its response.
Choose an API type for stated needs, explain one HTTP API request through routing, authorization, Lambda integration and response handling, and distinguish failure stages from evidence.
Know Lambda events, handlers, return values versus logs and execution roles, and that an HTTP exchange has a method, path and response status. Key terms are explained below. No AWS account or paid operation is needed: read fictional fixed examples and answer questions. This page creates or calls no real API and accepts no tokens.
Choose an API type from what the application needs
An API is an agreed interface through which applications exchange requests and responses. Our contract is “return information about the report named in a GET request.” API Gateway does not itself provide all report business logic or storage.
| Type | Example reason to choose it | Scope here |
|---|---|---|
| HTTP API | HTTP request/response access to Lambda with JWT authorization. | The worked example, after checking that its feature set meets the need. |
| REST API | Need private API endpoints, AWS WAF integration, request validation or usage plans. | Know the selection criteria; deployment is outside scope. |
| WebSocket API | Keep a connection open for two-way messages, including service-initiated updates. | Distinguish this from the request/response example. |
Lambda function URLs are another HTTP endpoint option. This lesson follows a design that uses HTTP API routes and a JWT authorizer. API Gateway is not mandatory for every Lambda application.
Choose an option to see the result and explanation.
A route matches the request; an integration selects the backend
| Term | Meaning | Fixed example |
|---|---|---|
| Method / path | The operation and target requested; GET asks to retrieve a representation. | GET /reports/demo-001 |
| Stage | A deployed API environment/reference, selected before route matching. | The intended stage has already been selected in this example. |
| Route | An HTTP method/path combination that matches accepted requests. | GET /reports/{reportId} |
| Integration | Configuration connecting a selected route to a backend such as Lambda. | Lambda proxy integration using payload format 2.0. |
- Client request → API GatewayHTTP request
- API Gateway → LambdaSynchronous invoke
- Client request
- Requests GET /reports/demo-001.
- API Gateway
- Matches the route and checks its configured JWT authorization.
- Lambda
- Handles the event and returns a response.
The arrows show the request direction. The response returns from Lambda through API Gateway to the calling client. API Gateway waits for the synchronous invocation and turns the result into an HTTP response; Lambda does not open a new direct connection to that client.
Choose an option to see the result and explanation.
Worked example: a request becomes an event, a result becomes HTTP
The event is the input delivered to Lambda. This HTTP API uses payload format 2.0, the selected event/response structure. The demo-001 path value appears in pathParameters.reportId, not an automatically created top-level event.reportId. Other API types and payload versions use different structures.
{
"version": "2.0",
"routeKey": "GET /reports/{reportId}",
"pathParameters": {
"reportId": "demo-001"
},
"requestContext": {
"http": {
"method": "GET"
},
"authorizer": {
"jwt": {
"claims": {
"sub": "reader-demo"
},
"scopes": [
"reports:read"
]
}
}
}
}The handler checks the report ID format, whether this caller may access that report, and whether the data exists. The fixture stipulates that demo-001 is accessible and returns state ready. The response contains report information, not the PDF itself. No storage connection or real data lookup is implemented or executed.
{
"statusCode": 200,
"headers": {
"content-type": "application/json"
},
"body": "{\"reportId\":\"demo-001\",\"state\":\"ready\"}",
"isBase64Encoded": false
}| Field | Meaning |
|---|---|
| statusCode: 200 | The HTTP status, stipulated here as a successful retrieval response. |
| headers | content-type identifies the body as JSON. |
| body | A JSON document represented as a string; the outer JSON escapes its quotation marks. |
| isBase64Encoded: false | The example body is not Base64 encoded. |
Choose an option to see the result and explanation.
Locate the failure; a status code alone is not a diagnosis
| Stage | Example | Evidence to inspect |
|---|---|---|
| API / stage / route | Wrong endpoint, stage, method or path; no matching route returns Not Found. | Endpoint, selected stage, defined routes and fallback settings. |
| JWT authorizer | An invalid audience can produce a 401 response. | Authorizer configuration and response details such as www-authenticate; do not share raw tokens. |
| Lambda invocation | A Lambda API rejection of the invocation returns 500. | Target function, invoke permission and available integration error details. |
| Function / response format | Function errors or invalid response format produce 502. | Matching function records, returned format and integration information. |
| Deliberate application HTTP result | A correctly formatted 404 when no report is found within the caller’s permitted lookup scope. | The application decision and explicit statusCode; separate from an invocation failure. |
| Case | Stated conditions | Conclusion |
|---|---|---|
| R2 | POST under the R1 design, with no matching route; Lambda was not invoked. | A method/route mismatch; not yet evidence of a report database problem. |
| R3 | GET route and authorization pass; Lambda runs and deliberately returns 404 for a missing report. | An application lookup result, not evidence that the GET route is absent. |
In an investigation, align time, API/stage and request identifiers, then compare configured access logs with function-side records. Stage access logging must be enabled separately; a missing log alone does not prove non-invocation. The 500/502 examples above are not a universal diagnosis of every such status. Do not assume API Gateway requestContext.requestId equals Lambda awsRequestId; align subject, version and time using established request correspondence.
Choose an option to see the result and explanation.
Check the waiting limit and the cost of the whole design
| Subject | Documented value | Do not infer |
|---|---|---|
| HTTP API integration timeout | Maximum 30 seconds; not adjustable. | Increasing Lambda timeout does not extend the HTTP API integration deadline. |
| HTTP API payload | 10 MB. | Not a promise that a 10 MB body fits the entire Lambda integration. |
| Ordinary synchronous Event Function | Maximum timeout 900 seconds; buffered requests/responses limited to 6 MB each. | Event wrapping and encoding also consume space; Lambda limits do not override API Gateway limits. |
HTTP/REST API costs depend on API calls and outbound transfer; WebSocket pricing also depends on messages and connection time. Include Lambda requests/duration and associated services such as logging. Reading this lesson uses no AWS resources, but deploying the same architecture is not automatically free. Check current Region, usage and account-specific Free Tier/credit conditions before deployment.
Choose an option to see the result and explanation.
Check, then explain in your own words
- Explain GET /reports/demo-001 using method, path, stage, route and integration.
- Separate JWT route authorization, API Gateway invoke permission, the execution role and object-level report access.
- Use the supplied evidence to explain R2/R3 failure stages and R4’s timeout mismatch.
Check your understanding: What remains to be designed after choosing Lambda for an HTTP report API?
Define method/path, stage/routes and integration, caller/object authorization, service permissions, event/response formats, deadlines, sizes and costs.
Lambda runs business logic. Designing access, permissions, data exchange and HTTP results explicitly also makes failure stages easier to investigate.
Sources and conditions checked
The official references used in this lesson are collected here with their scope, conditions and corresponding sections. Independent expert review and live AWS comparison have not been performed.
- Customize HTTP API access logsChecked:
Scope and conditionsGateway request ID and integration-side request identifiers/status fields have different scopes; correlate rather than assume equal strings.
Used in this lessonLocate the failure; a status code alone is not a diagnosis
Scope and conditionsawsRequestId identifies a Lambda invocation; align function/version, target and time window.
Used in this lessonLocate the failure; a status code alone is not a diagnosis
Scope and conditionsBoth products support RESTful APIs. Check private API endpoints, WAF, usage management and native JWT authorizers; a private integration is not a private API endpoint.
Used in this lessonChoose an API type from what the application needs
- API Gateway WebSocket APIsChecked:
Scope and conditionsPersistent bidirectional communication and service-initiated messages; implementation and reconnect guarantees are outside scope.
Used in this lessonChoose an API type from what the application needs
- Create routes for HTTP APIsChecked:
Scope and conditionsStage selection precedes method/path routing. Check path parameters, ANY/$default and unmatched routes; the example has one GET route and no fallback.
Used in this lessonA route matches the request; an integration selects the backend Locate the failure; a status code alone is not a diagnosis
Scope and conditionsPayload format 2.0 pathParameters, JWT claims and explicit response fields; the example is an excerpt, not a complete event.
Used in this lessonChoose an API type from what the application needs A route matches the request; an integration selects the backend Worked example: a request becomes an event, a result becomes HTTP Locate the failure; a status code alone is not a diagnosis
Scope and conditionsSignature, issuer, audience, time claims and route scopes; at least one configured scope is required. No token values or login implementation.
Used in this lessonA route matches the request; an integration selects the backend Worked example: a request becomes an event, a result becomes HTTP Separate caller authorization from AWS service permissions
Scope and conditionsSynchronous invocation, scoped invoke permission in a Lambda resource-based policy, and function URLs as another option; no open-endpoint deployment steps are executed or reproduced.
Used in this lessonChoose an API type from what the application needs A route matches the request; an integration selects the backend Separate caller authorization from AWS service permissions
Scope and conditionsThe execution role controls function access to AWS resources; distinguish it from user JWT authorization and API Gateway invoke permission.
Used in this lessonA route matches the request; an integration selects the backend Separate caller authorization from AWS service permissions
Scope and conditionsInvocation rejection, function/format errors, formatted application responses and no API Gateway retry; these examples do not identify every 500/502 cause.
Used in this lessonLocate the failure; a status code alone is not a diagnosis
Scope and conditionsAn example 401 and audience details in www-authenticate; do not submit real JWTs to an external debugger.
Used in this lessonLocate the failure; a status code alone is not a diagnosis
- Configure logging for HTTP APIsChecked:
Scope and conditionsStage access logging and requestId/routeKey/status fields; logging is not assumed to be universally enabled.
Used in this lessonLocate the failure; a status code alone is not a diagnosis
- Configure CORS for HTTP APIsChecked:
Scope and conditionsBrowser cross-origin behavior is separate from identity authorization and server processing; no wildcard-open configuration instructions.
Used in this lessonSeparate caller authorization from AWS service permissions
Scope and conditionsHTTP API maximum integration timeout of 30 seconds (not adjustable) and 10 MB payload limit; do not generalize to REST or WebSocket APIs.
Used in this lessonCheck the waiting limit and the cost of the whole design
- Lambda quotasChecked:
Scope and conditionsOrdinary synchronous Event Functions have a 900-second maximum and 6 MB buffered request/response limits; other Lambda compute modes are not generalized.
Used in this lessonCheck the waiting limit and the cost of the whole design
- Amazon API Gateway pricingChecked:
Scope and conditionsHTTP/REST call and outbound-transfer charges, WebSocket messages/connection time and associated service costs; no fixed regional price or Free Tier eligibility claim.
Used in this lessonCheck the waiting limit and the cost of the whole design
Scope and conditionsAPI keys are not authentication/authorization; usage-plan quotas and throttles are best effort. These are REST API features, not HTTP API features.
Used in this lessonSeparate caller authorization from AWS service permissions Check the waiting limit and the cost of the whole design