drive-apig
v2.4.2

Request lifecycle

sequenceDiagram
  participant C as Client
  participant AGW as API Gateway
  participant WAF as WAF
  participant L as Lambda
  participant EXT as Downstream systems

  C->>AGW: HTTPS request
  AGW->>WAF: Stage Web ACL evaluation
  WAF-->>AGW: allow/block
  AGW->>AGW: API key, usage plan, params, cache
  AGW->>L: Lambda proxy invocation
  L->>L: trace context, parse, validate
  L->>EXT: DynamoDB, SQS, SNS, HTTP, LLM
  L-->>AGW: statusCode, headers, body
  AGW-->>C: HTTPS response

Stages

  1. API Gateway stage and WAF - Terraform associates a regional WAF Web ACL with the API Gateway stage. WAF IP lists, managed rules, and rate-based rules can block the request before Lambda.
  2. API Gateway method request - private: true key validation, usage-plan throttling, request parameter validation, stage metrics, and optional cache happen outside service code.
  3. Lambda handler - handlers run on Node 20 or 22, arm64, bundled by Serverless/esbuild. Common work is trace-context extraction, input parsing, schema validation, side effects, and a Lambda proxy response.
  4. Async fan-out - many deployed HTTP routes only enqueue work. For example, POST /leads/in/queue writes to FIFO SQS; worker Lambdas such as leadsInboundProcess run from SQS and are documented as local harnesses only when they have HTTP replay routes for offline testing.

CORS

Every HTTP event declares CORS config with origin: '*' and a shared allow-list (Content-Type, Authorization, X-Api-Key, SigV4 headers). Some services add headers such as mode or sentry-trace. API Gateway generates preflight OPTIONS from the event config.

Event-driven handlers

Do not assume every documented operation is a deployed HTTP route. OpenAPI includes local HTTP replay harnesses for some SQS workers so agents and developers can test request/response shapes locally. Those operations are marked with x-drive-deployment: local-test-http and x-drive-trigger.

Errors

API Gateway errors are small JSON bodies and occur before Lambda. Handler errors are service-specific JSON and should include message or error; newer handlers also include requestId and success: false.

See Error codes.

Esc
Esc Close