Do you need VTL templates, direct AWS service integrations,
Edge-optimized (CloudFront-backed) endpoints, or usage plan / API key management?
  → YES: Use REST API. The capability premium is justified.
  → NO:  Use HTTP API. You are paying 70% more for nothing.

// The exact event shape for REST API Lambda Proxy Integration (APIGatewayProxyEvent)
export const handler = async (
  event: AWSLambda.APIGatewayProxyEvent
): Promise<AWSLambda.APIGatewayProxyResult> => {
  // Key fields your handler will actually use:
  const {
    httpMethod,           // "GET" | "POST" | "PUT" | "DELETE" | "PATCH"
    path,                 // "/users/42" (the actual URL path)
    pathParameters,       // { userId: "42" } (from {userId} in the route)
    queryStringParameters,// { page: "2", limit: "20" } (from ?page=2&limit=20)
    headers,              // { Authorization: "Bearer eyJ...", "Content-Type": "application/json" }
    body,                 // Raw string body (must be JSON.parsed if Content-Type is application/json)
    isBase64Encoded,      // true if binary body was base64-encoded by API GW
    requestContext: {
      requestId,          // API Gateway request ID — use as correlationId in logs
      authorizer: {
        claims,           // Populated by Cognito User Pool authorizer (JWT claims)
        principalId,      // Populated by Lambda Authorizer
        context,          // Custom key-value pairs returned by Lambda Authorizer
      }
    }
  } = event

  // ❌ Common mistake: accessing body without JSON.parse
  // event.body is ALWAYS a string in Lambda Proxy — never a parsed object
  const wrong = event.body.userId           // undefined — body is a string, not an object

  // ✅ Correct
  const payload = JSON.parse(event.body!)  // Parse the string body
  const { userId } = payload
}

// ✅ Correct Lambda Proxy response — API Gateway reads these exact fields
return {
  statusCode: 200,           // Required: HTTP status code (number)
  headers: {                 // Optional but recommended: set Content-Type and CORS headers
    'Content-Type': 'application/json',
    'Access-Control-Allow-Origin': 'https://app.example.com',
  },
  body: JSON.stringify({     // Required: must be a STRING — not an object
    id: user.id,
    name: user.name,
  }),
  isBase64Encoded: false,    // Optional: set true only for binary responses
}

// ❌ These all produce 502 Bad Gateway from API Gateway:
return { id: '42', name: 'Alice' }           // Missing statusCode and body fields
return { statusCode: 200, body: { id: '42'}} // body must be string, not object
return 'Hello World'                          // Plain string — not the expected shape

export const handler = async (
  event: AWSLambda.APIGatewayProxyEventV2
): Promise<AWSLambda.APIGatewayProxyResultV2> => {
  // v2 differences from v1:
  const {
    routeKey,             // "GET /users/{userId}" — combines method + route
    rawPath,              // "/users/42"
    rawQueryString,       // "page=2&limit=20" (raw string, not parsed)
    pathParameters,       // { userId: "42" }
    body,                 // Still a string — still needs JSON.parse
    requestContext: {
      http: {
        method,           // "GET" — nested under requestContext.http in v2
        path,
        sourceIp,
      },
      requestId,
    }
  } = event

  // v2 allows shorthand response (statusCode defaults to 200):
  return JSON.stringify({ id: '42', name: 'Alice' }) // ← valid in v2: string response = 200
  // Or full form:
  return { statusCode: 200, body: JSON.stringify({ id: '42' }) }
}

// API Gateway Cognito authorizer configuration (CDK)
import { CognitoUserPoolsAuthorizer } from 'aws-cdk-lib/aws-apigateway'
import { UserPool } from 'aws-cdk-lib/aws-cognito'

const userPool = UserPool.fromUserPoolId(this, 'UserPool', 'us-east-1_abc123')

const authorizer = new CognitoUserPoolsAuthorizer(this, 'UserPoolAuthorizer', {
  cognitoUserPools: [userPool],
  identitySource: 'method.request.header.Authorization', // Bearer token location
})

// Apply to a route
api.root.addResource('orders').addMethod('GET', lambdaIntegration, {
  authorizer,
  authorizationType: AuthorizationType.COGNITO,
})

// Handler receives decoded Cognito claims — no token validation needed in handler
export const handler = async (event: AWSLambda.APIGatewayProxyEvent) => {
  const claims = event.requestContext.authorizer?.claims
  const userId = claims?.sub              // Cognito user UUID
  const email = claims?.email
  const groups = claims?.['cognito:groups']?.split(',') ?? []

  if (!groups.includes('admin')) {
    return { statusCode: 403, body: JSON.stringify({ error: 'Forbidden' }) }
  }
  // proceed...
}

// Lambda Authorizer handler (token-based)
export const authorizerHandler = async (
  event: AWSLambda.APIGatewayTokenAuthorizerEvent
): Promise<AWSLambda.APIGatewayAuthorizerResult> => {
  const token = event.authorizationToken.replace('Bearer ', '')

  try {
    const payload = await verifyJwt(token, process.env.JWKS_URL!)
    const userId = payload.sub

    // Return allow policy + context (passed to downstream Lambda in requestContext.authorizer)
    return {
      principalId: userId,
      policyDocument: {
        Version: '2012-10-17',
        Statement: [{
          Action: 'execute-api:Invoke',
          Effect: 'Allow',
          Resource: event.methodArn,  // Scope to this specific method
        }]
      },
      context: {
        userId,
        email: payload.email,
        tier: payload['custom:tier'] ?? 'free',
      }
    }
  } catch {
    throw new Error('Unauthorized') // API GW returns 401 on thrown Error
  }
}

// REST API: Lambda Authorizer with caching (CDK)
import { TokenAuthorizer } from 'aws-cdk-lib/aws-apigateway'

const authorizer = new TokenAuthorizer(this, 'TokenAuth', {
  handler: authorizerFn,
  resultsCacheTtl: Duration.seconds(300),   // Cache the policy for 5 minutes
  // Cache key: the token value by default (TOKEN authorizer)
  // For REQUEST authorizer: identitySource specifies which headers/params form the cache key
})

// Cache math:
// At 10M req/month with TTL=300s:
// Unique token active windows = 10M / (300s × assumed req rate) ≈ much lower
// Realistically: 99%+ cache hit rate for active user sessions
// Result: ~33K Authorizer invocations instead of 10M → 99.7% cost reduction

// CDK: explicit deployment with stage configuration
import { Deployment, Stage, LogGroupLogDestination, MethodLoggingLevel } from 'aws-cdk-lib/aws-apigateway'
import { LogGroup } from 'aws-cdk-lib/aws-logs'

const api = new RestApi(this, 'OrderApi', {
  deployOptions: {
    stageName: 'prod',
    loggingLevel: MethodLoggingLevel.INFO,  // Enable execution logging
    dataTraceEnabled: false,                 // Don't log full request/response bodies in prod
    metricsEnabled: true,
    throttlingBurstLimit: 500,
    throttlingRateLimit: 1000,
  }
})

// Stage variables: key-value pairs accessible in Lambda via event.stageVariables
// Useful for environment-specific routing without code changes
// stageVariables.lambdaAlias → "prod" or "staging" → used in Lambda ARN for alias routing

Account limit: 10,000 req/s (default) — shared across all APIs in the region
  └── Stage limit: set per stage (overrides toward lower)
        └── Method limit: set per method (further overrides for specific routes)

// CDK: method-level throttling for a specific high-traffic route
const ordersResource = api.root.addResource('orders')
ordersResource.addMethod('POST', orderIntegration, {
  methodResponses: [{ statusCode: '200' }],
})

// Override throttling for the POST /orders method specifically
const deployment = new Deployment(this, 'Deployment', { api })
const stage = new Stage(this, 'ProdStage', {
  deployment,
  methodOptions: {
    'POST/orders': {
      throttlingBurstLimit: 100,   // Max burst: 100 simultaneous
      throttlingRateLimit: 50,     // Steady state: 50 req/s
    }
  }
})