INFRASTRUCTURE LEARNINGINFRASTRUCTURE LEARNING
インフラ大全インフラ大全IT INFRASTRUCTURE / LEARNING
Infrastructure learning guide
Find a lesson or lab/

Esc to close · Search terms stay on your device

LEARNING日本語

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.

What you will learn

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.

Prerequisite

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.

Read the three product names through their use cases
TypeExample reason to choose itScope here
HTTP APIHTTP request/response access to Lambda with JWT authorization.The worked example, after checking that its feature set meets the need.
REST APINeed private API endpoints, AWS WAF integration, request validation or usage plans.Know the selection criteria; deployment is outside scope.
WebSocket APIKeep 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 report API needs Lambda and JWT authorization, with no private API endpoint or usage-plan requirement. Which is a reasonable starting point?
Read the answer and reason

Answer: HTTP API · HTTP APIs support this Lambda/JWT combination. Choose from required features, not price alone.

A route matches the request; an integration selects the backend

Four terms for reading a request
TermMeaningFixed example
Method / pathThe operation and target requested; GET asks to retrieve a representation.GET /reports/demo-001
StageA deployed API environment/reference, selected before route matching.The intended stage has already been selected in this example.
RouteAn HTTP method/path combination that matches accepted requests.GET /reports/{reportId}
IntegrationConfiguration connecting a selected route to a backend such as Lambda.Lambda proxy integration using payload format 2.0.
Receive the request, run the backend, return an HTTP response
Receive the request, run the backend, return an HTTP response1: Client request — HTTP request — API Gateway. 2: API Gateway — Synchronous invoke — Lambda12Client requestAPI GatewayLambdaReceive the request, run the backend, return an HTTP response1: Client request — HTTP request — API Gateway. 2: API Gateway — Synchronous invoke — Lambda12Client requestAPI GatewayLambda
  1. Client request → API GatewayHTTP request
  2. 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.

R1 receives POST /reports/demo-001. Does matching the path text alone send it to Lambda?
Read the answer and reason

Answer: No; this design has no matching route · No POST, ANY or $default route exists here, so no matching integration is selected. A real fallback would change that outcome.

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.

R1: HTTP API event excerpt, for reading onlyScroll horizontally to read long lines. Use arrow keys in the code area.
{
  "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.

R1: explicit Lambda response objectScroll horizontally to read long lines. Use arrow keys in the code area.
{
  "statusCode": 200,
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"reportId\":\"demo-001\",\"state\":\"ready\"}",
  "isBase64Encoded": false
}
Separate the response envelope from the HTTP body
FieldMeaning
statusCode: 200The HTTP status, stipulated here as a successful retrieval response.
headerscontent-type identifies the body as JSON.
bodyA JSON document represented as a string; the outer JSON escapes its quotation marks.
isBase64Encoded: falseThe example body is not Base64 encoded.

Choose an option to see the result and explanation.

Where does the handler read the report ID in the R1 excerpt?
Read the answer and reason

Answer: event.pathParameters.reportId · Read the route parameter from payload format 2.0 pathParameters, then validate it and enforce object-level authorization.

Separate caller authorization from AWS service permissions

A JWT (JSON Web Token) carries claims such as identity information. The issuer identifies the identity system that issued the token; the audience identifies its intended recipient. A JWT authorizer validates the token against configured signature, issuer, audience and time conditions, plus route scopes when configured. A scope is a named capability, such as reports:read. Authentication concerns the trustworthiness of the presented identity; authorization concerns permission for the requested use. Merely decoding a string does not validate it.

Each permission has a different caller and target
BoundaryWhat to checkWhat it does not replace
Caller → API routeJWT authorizer and, here, the reports:read route scope.Object-level report authorization or the function’s AWS permissions.
API Gateway → LambdaFor R1, invoke permission in the function’s resource-based policy, scoped to the intended API and other conditions.JWT validation for the human/application caller.
Lambda → AWS resourcesThe function execution role and permissions for target resources.Authorization for a person using an API route.
Caller → individual reportApplication checks connecting validated identity to report ownership/sharing rules.A route scope alone does not grant access to every report.

Choose an option to see the result and explanation.

May a caller with a validated reports:read token receive every user’s reports?
Read the answer and reason

Answer: Check the caller’s access to that report in the application · JWT validation and a route scope do not complete object-level authorization. Compare the validated identity with ownership/sharing rules.

JWT authorization passes, but API Gateway lacks permission to invoke the function. What boundary should be checked?
Read the answer and reason

Answer: Invoke permission in the function’s resource-based policy · Caller-to-API and API-Gateway-to-function are separate boundaries. Inspect invoke permission scoped to the intended API.

Locate the failure; a status code alone is not a diagnosis

Separate gateway, invocation and application response stages
StageExampleEvidence to inspect
API / stage / routeWrong endpoint, stage, method or path; no matching route returns Not Found.Endpoint, selected stage, defined routes and fallback settings.
JWT authorizerAn invalid audience can produce a 401 response.Authorizer configuration and response details such as www-authenticate; do not share raw tokens.
Lambda invocationA Lambda API rejection of the invocation returns 500.Target function, invoke permission and available integration error details.
Function / response formatFunction errors or invalid response format produce 502.Matching function records, returned format and integration information.
Deliberate application HTTP resultA 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.
Fixed R2/R3 cases: distinguish two Not Found outcomes
CaseStated conditionsConclusion
R2POST under the R1 design, with no matching route; Lambda was not invoked.A method/route mismatch; not yet evidence of a report database problem.
R3GET 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.

Given the evidence in R2 and R3, which conclusion is justified?
Read the answer and reason

Answer: Investigate routing for R2 and the application lookup for R3 · R2 fails at route matching; R3 returns an application 404 after invocation. Follow the supplied evidence instead of broadening unrelated permissions.

Check the waiting limit and the cost of the whole design

Documented limits checked on 2026-10-26 for this design
SubjectDocumented valueDo not infer
HTTP API integration timeoutMaximum 30 seconds; not adjustable.Increasing Lambda timeout does not extend the HTTP API integration deadline.
HTTP API payload10 MB.Not a promise that a 10 MB body fits the entire Lambda integration.
Ordinary synchronous Event FunctionMaximum 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.

For R4, does setting only Lambda timeout to 900 seconds guarantee the final result in the same HTTP API response after 45 seconds?
Read the answer and reason

Answer: No; the processing design must fit the HTTP API deadline · A 45-second final result does not fit 30 seconds; reduce work or separate acceptance and completion.

What is the appropriate cost check before deploying this design on AWS?
Read the answer and reason

Answer: Check API Gateway, Lambda, transfer, logging and applicable usage conditions · API calls alone do not represent the full bill. Verify applicable Free Tier terms and periods for the account.

Check, then explain in your own words

  1. Explain GET /reports/demo-001 using method, path, stage, route and integration.
  2. Separate JWT route authorization, API Gateway invoke permission, the execution role and object-level report access.
  3. 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.