Amazon API Gateway

What Is Amazon API Gateway?

Amazon API Gateway is AWS's fully managed service for creating, publishing, securing, monitoring, and monetizing APIs at any scale. For the DVA-C02 exam, Amazon API Gateway sits squarely in Domain 1 (Development with AWS Services) because developers use Amazon API Gateway as the HTTPS front door that fronts AWS Lambda functions, integrates with any HTTP backend, and exposes AWS service APIs directly to internet or VPC clients without running a single EC2 instance. Amazon API Gateway removes the need to build and operate your own TLS termination, request validation, authorization, throttling, and quota enforcement layers — all of which would otherwise be boilerplate code inside every microservice.

The DVA-C02 exam guide calls out Amazon API Gateway under Task Statement 1.3 ("Develop code for applications hosted on AWS") and Task Statement 3.3 ("Implement application design into application code"). Amazon API Gateway questions test three practical skills: wiring Amazon API Gateway to a Lambda function using the correct integration type, protecting Amazon API Gateway endpoints with the correct authorizer, and operating an Amazon API Gateway deployment with usage plans, stage variables, canary releases, throttling, and caching. Every serverless reference architecture AWS ships — web backends, mobile backends, public APIs, chat applications, IoT command endpoints — has Amazon API Gateway at the edge, so the concepts in this topic compound across the rest of the DVA-C02 blueprint.

Amazon API Gateway offers three API flavors that a developer must distinguish cold: REST API (the original, feature-rich variant), HTTP API (cheaper and lower-latency, launched 2019), and WebSocket API (bidirectional real-time messaging). This DVA-C02 study guide walks through every knob that Amazon API Gateway exposes, from request-response mapping templates written in Velocity Template Language (VTL) through Cognito User Pool authorizers, Lambda authorizers, usage plans, stage variables, canary deployments, throttling, caching, CORS preflight, AWS WAF integration, custom domain names, and OpenAPI import/export. When you finish, Amazon API Gateway questions on DVA-C02 should feel like free points.

Plain-Language Explanation: Amazon API Gateway

Amazon API Gateway handles so many responsibilities that beginners often struggle to pin down its mental model. Three analogies from different domains make Amazon API Gateway click — pick whichever one fits your intuition best.

Analogy 1 — Amazon API Gateway as the Hotel Front Desk

Picture Amazon API Gateway as the front desk of a large hotel. Guests (API callers) arrive at the lobby with different needs: room service, spa booking, valet parking, express checkout. The front desk (Amazon API Gateway) is the single entry point. It checks identification (authorizer), consults the reservation system for room access (usage plan and API key), routes the request to the right department (Lambda function, HTTP backend, AWS service integration), translates the request into the department's internal vocabulary (mapping template, VTL), translates the department's response back into guest-friendly language (response mapping), and tracks every interaction in the hotel log (CloudWatch Logs, access logs). The front desk also enforces house rules: no more than 10 requests per minute per guest (throttling), a maximum of 500 requests per day (quota), and certain rooms are off-limits without a special keycard (IAM or Cognito authorizer). The hotel's rooms, spa, and kitchen (your Lambda functions and backends) never talk to guests directly — everything flows through the front desk. This is exactly how Amazon API Gateway insulates your backend from the messy, hostile internet.

Analogy 2 — Amazon API Gateway as the Swiss Army Knife

Amazon API Gateway is the Swiss army knife of API development. The REST API blade gives you a full workbench: request validation, response mapping, API keys, usage plans, caching, WAF integration, private APIs, mutual TLS. The HTTP API blade is the lightweight pocket blade: JWT authorizers out of the box, lower cost, lower latency, ideal for straightforward proxy-to-Lambda workloads. The WebSocket API blade is the bidirectional blade: $connect, $disconnect, and $default routes let the server push messages to clients, which REST and HTTP APIs cannot do. Each blade shares the same handle (the Amazon API Gateway control plane, billing, monitoring) but specializes in a different cut. Choosing the wrong blade for the job costs money and latency: using REST API where HTTP API would suffice can triple your per-request cost. DVA-C02 loves this trap.

Analogy 3 — Amazon API Gateway as the Airport Control Tower

Amazon API Gateway is the control tower of a busy airport. Every plane (HTTP request) must contact the tower before touching down on a runway (backend). The tower authenticates the pilot (authorizer), confirms the flight plan matches the plane's clearance (request validation), assigns a runway based on current load (throttling, burst control), holds inbound traffic when all runways are full (429 Too Many Requests), and keeps every transmission on the flight recorder (CloudWatch metrics, X-Ray traces). Canary deployments work like staged runway openings: 10% of arrivals go to the new runway, 90% to the proven one, then ratchet up. Stage variables are flight-plan variables: prod stage points to production runway, dev stage points to the testing runway, same tower same frequency different targets. WAF is the TSA checkpoint on the access road filtering threats before planes even reach the tower.

With the hotel front desk, Swiss army knife, and airport control tower analogies locked in, the rest of Amazon API Gateway's features slot neatly into the mental model.

Amazon API Gateway API Types — REST vs HTTP vs WebSocket

The single most-tested Amazon API Gateway decision on DVA-C02 is picking the right API type. Amazon API Gateway ships three types, each with its own feature matrix, pricing, and latency profile.

REST API

The original Amazon API Gateway offering. REST API is the feature-complete variant and supports every Amazon API Gateway capability: request validation, mapping templates (VTL), method-level IAM/Cognito/Lambda authorizers with result caching, API keys, usage plans, per-method caching, request/response transformations, private integrations via VPC Link to NLB, private REST APIs accessible only from a VPC, mutual TLS, AWS WAF, and OpenAPI import/export.

Use REST API when you need VTL mapping templates, method-level throttling that differs across routes, API keys with usage plans for monetization, private APIs inside a VPC, mutual TLS, or integration with AWS services other than Lambda (for example DynamoDB or Step Functions directly).

HTTP API

Launched in 2019 to be Amazon API Gateway's cheaper, lower-latency variant for common serverless use cases. HTTP API costs about 70% less than REST API and delivers lower p99 latency because the runtime path is shorter. HTTP API natively understands JWT tokens (typically from Amazon Cognito User Pools), supports CORS as a one-click setting, and supports automatic deployments.

HTTP API trades features for simplicity. What HTTP API does not support: VTL mapping templates, API keys, usage plans, per-method caching (no caching at all), request validation with JSON schema, AWS WAF, private APIs (only public and VPC Link v2), mutual TLS with custom CA, and AWS X-Ray (added later for some scenarios).

Use HTTP API when your workload is a straight Lambda proxy or HTTP backend proxy with JWT authorization and you do not need the advanced REST API features listed above.

WebSocket API

Amazon API Gateway's bidirectional variant. WebSocket API manages persistent full-duplex connections so the server can push messages to clients — essential for chat applications, real-time dashboards, collaborative editing, live sports scores, and IoT command-and-control. Routes in WebSocket API are keyed on a route selection expression (commonly $request.body.action) rather than HTTP path+method. Three built-in routes exist: $connect (fires on new connection, ideal for authorization), $disconnect (fires on teardown), and $default (fallback).

Connections are identified by a connectionId. To send a message to a client, a Lambda function calls the @connections management API using the connection ID. Billing is per connection-minute plus per message, so idle connections cost less than active ones but still cost.

REST vs HTTP vs WebSocket Feature and Cost Matrix

Amazon API Gateway Integration Types — How the Backend Is Wired

Amazon API Gateway sits in front of your backend, but "backend" can mean many things. The integration type tells Amazon API Gateway how to invoke the backend and how to shape the payload. For REST API you get six integration types; HTTP API has a reduced set.

Lambda Proxy Integration (AWS_PROXY)

Lambda proxy integration is the default and most common wiring. Amazon API Gateway packages the entire HTTP request (method, path, headers, query parameters, body, request context) into a single JSON event object and hands it to Lambda. The Lambda function must return a JSON object in a specific shape: {statusCode, headers, body, isBase64Encoded}. Amazon API Gateway then returns that shape as the HTTP response. No mapping templates are involved — the developer owns parsing and formatting inside the Lambda function.

Use Lambda proxy for 95% of Lambda-backed workloads. It is simpler to reason about, faster to develop, and compatible with frameworks like AWS SAM, Serverless Framework, and the Lambda Powertools libraries.

Lambda Non-Proxy Integration (AWS, custom integration)

Lambda non-proxy integration (also called "custom integration") uses VTL mapping templates on both request and response. You write an integration request template that transforms the incoming HTTP request into the exact JSON shape your Lambda expects, and an integration response template that reshapes the Lambda output into the HTTP response. This decouples the Lambda function's internal contract from the public API surface.

Use Lambda non-proxy when you must keep the Lambda function agnostic of HTTP (for example, a function reused from Step Functions that takes a flat object), when you want to strip or rename fields at the edge, or when you need per-status-code response mapping.

HTTP Integration and HTTP Proxy

HTTP integration points Amazon API Gateway at any public HTTP backend — an ELB, a third-party API, or an on-premises endpoint reachable from the internet. HTTP proxy passes the request through unchanged; HTTP non-proxy (custom integration) uses mapping templates the same way Lambda non-proxy does.

AWS Service Integration

Amazon API Gateway can invoke many AWS service APIs directly, without a Lambda in between. Common examples: PUT to DynamoDB, start a Step Functions execution, publish to SNS, send to SQS, upload to S3. You model the call as a SigV4-signed request, and Amazon API Gateway assumes an IAM role to perform the action. This "no Lambda" pattern saves cost and cold-start latency when the work is a simple AWS service call.

Mock Integration

Mock integration returns a canned response without calling any backend. Use it for CORS preflight OPTIONS responses, placeholder endpoints during development, or stubbing dependencies for load tests.

VPC Link (Private Integration)

VPC Link lets Amazon API Gateway reach resources inside a private VPC. For REST API, VPC Link targets a Network Load Balancer (NLB) fronting ECS tasks, EC2 instances, or on-premises resources reached via Direct Connect/VPN. For HTTP API, VPC Link v2 targets ALB, NLB, or AWS Cloud Map services, which is more flexible.

Lambda Proxy vs Lambda Non-Proxy — The Canonical Trap

The single highest-frequency Amazon API Gateway trap on DVA-C02 is distinguishing Lambda proxy from Lambda non-proxy. Memorize this:

• Lambda proxy (AWS_PROXY): no mapping templates, Lambda must return the exact API Gateway response shape, simpler, default for most serverless apps.
• Lambda non-proxy (AWS): mapping templates required on request and response, Lambda stays HTTP-agnostic, useful when reshaping is needed at the edge.

If the question mentions VTL, mapping templates, or request transformation, it is Lambda non-proxy. If the question mentions event.requestContext, event.pathParameters, or the {statusCode, body, headers} return shape, it is Lambda proxy.

Request and Response Mapping Templates (VTL)

Velocity Template Language (VTL) is the scripting language Amazon API Gateway uses to transform requests and responses in non-proxy integrations. Mapping templates are attached to either the integration request (incoming HTTP → backend payload) or the integration response (backend output → HTTP response), and are scoped to a specific content type (typically application/json).

Key VTL Variables

Amazon API Gateway exposes a rich $input, $context, $stageVariables, and $util object to every template:

• $input.body — raw request body as a string.
• $input.json('$.path') — JSONPath extraction returning JSON.
• $input.params() — combined path, query, header parameters.
• $input.params('name') — single parameter lookup across path, query, headers.
• $context.identity.sourceIp — caller's IP address (also $context.identity.userAgent, $context.identity.cognitoIdentityId).
• $context.authorizer.claims.sub — authenticated Cognito user sub (when Cognito authorizer fires).
• $context.authorizer.principalId — custom principal from Lambda authorizer.
• $stageVariables.varName — stage variable value for the current stage.
• $util.escapeJavaScript(value) — safely escape a string for JSON.
• $util.base64Encode(value) / $util.base64Decode(value) — binary helpers.

Example — Request Mapping Template

{
  "userId": "$context.authorizer.claims.sub",
  "product": $input.json('$.product'),
  "quantity": $input.json('$.quantity'),
  "sourceIp": "$context.identity.sourceIp",
  "env": "$stageVariables.targetEnv"
}

This transforms an incoming REST request into a flat object the Lambda (or Step Functions, DynamoDB, etc.) expects, enriched with the authenticated user's sub and the stage environment name.

Integration Response Mapping and Status Codes

On the response side, Amazon API Gateway pattern-matches the backend's error output against method responses using regex on the error string. For example, a Lambda that throws "NotFound: user abc123" can be mapped to a 404 status with a cleaned-up body:

{
  "error": "USER_NOT_FOUND",
  "message": "$util.escapeJavaScript($input.path('$.errorMessage'))"
}

Amazon API Gateway Authorization Options

Amazon API Gateway supports five authorization mechanisms for REST API and a reduced set for HTTP/WebSocket. Picking the right authorizer is a recurring DVA-C02 question.

1. IAM Authorization (AWS_IAM)

Uses SigV4 signatures. Best for internal service-to-service calls where the caller already has AWS credentials (EC2 instance role, Lambda execution role, another AWS account). The IAM policy on the caller must grant execute-api:Invoke on the Amazon API Gateway ARN.

Use case: an internal admin Lambda calling an internal API, or a mobile app using Cognito Identity Pools to get temporary AWS credentials and signing requests.

2. Cognito User Pool Authorizer

Amazon API Gateway validates a JSON Web Token (JWT) issued by a Cognito User Pool. The client authenticates against Cognito, receives an ID token and access token, then sends the token in the Authorization header (typically as a bearer token). Amazon API Gateway verifies signature, issuer, audience, and expiration, and exposes the claims as $context.authorizer.claims.* for downstream use.

Use case: consumer-facing mobile or web app with sign-up/sign-in handled by Cognito.

3. Lambda Authorizer (TOKEN type)

A Lambda authorizer is a developer-written function that Amazon API Gateway invokes before routing the request. The TOKEN type receives only a token value (from a specific header, commonly Authorization) and must return an IAM policy document permitting or denying the invocation. Use TOKEN for bearer-token schemes: JWTs from a non-Cognito issuer (Auth0, Okta, Firebase), OAuth 2.0 opaque tokens, or custom tokens.

4. Lambda Authorizer (REQUEST type)

The REQUEST type receives the full request context — headers, query strings, stage variables, source IP, path — and decides based on any combination of them. Use REQUEST when authorization depends on more than a single token: multi-header schemes, IP allowlists combined with tokens, or business-rule checks against external systems.

Lambda Authorizer Result Caching

Both TOKEN and REQUEST authorizers support caching via the authorizer result TTL setting (default 300 seconds, max 3600 seconds, 0 disables caching). Amazon API Gateway caches the returned IAM policy keyed on the identity source (the token for TOKEN type; a configurable subset of headers/query/stage variables for REQUEST type). Caching dramatically cuts Lambda authorizer invocations and latency, but also means a revoked token remains valid for up to the TTL — design for this.

The cache key for REQUEST authorizers is defined in the identity sources field. If your identity source includes $request.header.Authorization, $request.header.X-Tenant-Id, the cache keys on both. Identical values hit the cache; different values miss and re-invoke the authorizer.

5. API Keys Plus Usage Plans (Not True Authorization)

API keys are not an authentication mechanism on their own — a leaked API key grants access. They exist to identify a caller for quota and throttling enforcement via usage plans. Combine API keys with another authorizer (IAM, Cognito, Lambda) for real security.

Authorizer Type Decision Matrix

Usage Plans and API Keys — Throttling and Quota

Usage plans are an REST-API-only feature that let you enforce throttling (requests per second) and quota (requests per day/week/month) per API key. They are the foundation of API monetization patterns.

Creating a Usage Plan

A usage plan references one or more API stages and defines three parameters:

• Throttle rate limit — steady-state requests per second allowed.
• Throttle burst limit — size of the token bucket for short spikes.
• Quota — rolling window cap (e.g., 10,000 requests per day).

You then associate API keys with the usage plan. When a request arrives carrying x-api-key, Amazon API Gateway looks up the key's usage plan and applies the throttling and quota enforcement. Exceeding the limit returns HTTP 429 Too Many Requests.

Tiered Plans Pattern

A classic monetization pattern uses three usage plans — Free (100 req/day), Silver (10,000 req/day), Gold (1,000,000 req/day) — with different throttle and burst settings. Each customer gets an API key tied to their tier. Upgrading a customer means moving their key to a higher plan.

Required Configuration Steps

1. Create the API key (or generate a distinct key per customer).
2. Create the usage plan with throttle and quota.
3. Associate the usage plan with the stage(s) you want metered.
4. Associate the API key with the usage plan.
5. Mark the method as API Key Required: true on the stage.
6. Client sends the key in the x-api-key header on every request.

Stage Variables and Canary Deployments

Stage Variables

Stage variables are name-value pairs bound to a specific Amazon API Gateway stage (for example dev, qa, prod). They behave like environment variables for your API: the same deployment artifact points at different backends depending on which stage it is invoked through. Common uses:

• Pointing at different Lambda aliases per stage ($stageVariables.lambdaAlias) so prod invokes the LIVE alias and dev invokes the DEV alias.
• Embedding stage-specific values in mapping templates ($stageVariables.targetEnv).
• Rewriting HTTP integration endpoints per stage (https://$stageVariables.backendHost/orders).

Stage variables are not a secret-management tool — they are plain-text configuration visible in the console. Use AWS Systems Manager Parameter Store or AWS Secrets Manager for secrets.

Canary Deployments

Amazon API Gateway REST API supports native canary deployments. A canary is a second deployment attached to an existing stage that receives a configurable percentage of traffic. Both deployments share the same stage and stage variables are independently configurable (so the canary can point at a new Lambda alias or backend while the baseline stays on the current one).

Canary workflow:

1. Deploy v1 to the prod stage. 100% of traffic goes to v1.
2. Create a canary on the prod stage pointing to deployment v2, with 10% traffic.
3. Observe CloudWatch metrics and access logs for the canary.
4. If healthy, ratchet to 50%, then 100%, or promote the canary to the base deployment.
5. If unhealthy, delete the canary — all traffic stays on v1.

Canaries support per-canary stage variables, per-canary Amazon API Gateway caching, and separate CloudWatch metrics scoped to $context.canary.

Amazon API Gateway Throttling — Account, Stage, Method, and Burst

Throttling on Amazon API Gateway is a layered model. Requests are checked against multiple limits in order; the most restrictive limit wins.

Account-Level Throttling (Soft Limit)

Every AWS account has a default Amazon API Gateway throttle of 10,000 requests per second steady-state with a 5,000-request burst across all APIs in the Region. This is a soft limit raised via AWS Support. If your account-level throttle is exceeded, callers see 429s regardless of per-API settings.

Stage-Level Throttling

Configure a throttle rate limit and burst limit per stage. This caps the entire stage (all methods combined). Useful for protecting a test stage from runaway load.

Method-Level Throttling

Override stage-level settings on a specific route+method combination. Useful when one endpoint is dramatically cheaper or more expensive than the rest and needs tighter or looser limits. Configure under Stage > Method Settings.

Per-Client (Usage Plan) Throttling

Applies per API key on top of the global throttles. The most restrictive of (account, stage, method, usage-plan) wins.

Burst Explained

Amazon API Gateway uses a token bucket algorithm. The steady-state rate refills tokens; the burst size is the bucket depth. A burst of 5,000 with a rate of 10,000/s means a caller can spike up to 5,000 requests instantly, but subsequent requests refill at 10,000/s. Bursts handle natural request clustering without penalizing well-behaved callers.

HTTP 429 Too Many Requests

When throttled, Amazon API Gateway returns HTTP 429 with a Retry-After header (when available). Clients should implement exponential backoff with jitter. The AWS SDKs do this automatically.

Amazon API Gateway Caching

Amazon API Gateway REST API supports a dedicated response cache at the stage level. When enabled, Amazon API Gateway provisions a cache cluster and caches GET responses keyed on request parameters.

Cache Cluster Sizes

Amazon API Gateway offers cache cluster sizes from 0.5 GB to 237 GB, billed per hour regardless of usage. Sizes available: 0.5, 1.6, 6.1, 13.5, 28.4, 58.2, 118, 237 GB. Larger clusters mean higher hit ratio and higher cost.

TTL

Default TTL is 300 seconds, configurable from 0 (disabled) to 3600 seconds per method. Shorter TTLs mean fresher data but lower hit ratio; longer TTLs mean stale data risk but higher hit ratio. Pick based on how often the underlying data changes.

Cache Key Parameters

By default the cache key is the method path. Add request parameters (headers, query strings, path parameters, stage variables) to the cache key when responses vary by them. Example: caching /products/{id} naturally varies by {id}; caching /search?q=... should include the q query string as a cache key parameter.

Cache Invalidation

Clients can invalidate a cache entry by sending the Cache-Control: max-age=0 header if they have the InvalidateCache permission (IAM policy on the calling identity). Otherwise the request is served from cache regardless of the header.

Encryption at Rest

Enable cache encryption at rest for compliance. It adds no latency but cannot be toggled without recreating the cache cluster.

CORS — Cross-Origin Resource Sharing and Preflight

Browsers enforce the Same-Origin Policy: a page served from https://app.example.com cannot send XHR/fetch requests to https://api.example.com unless the API explicitly opts in via CORS response headers. Amazon API Gateway's CORS behavior differs slightly across API types.

Preflight OPTIONS Requests

For "non-simple" requests (any Content-Type other than application/x-www-form-urlencoded, multipart/form-data, or text/plain, or any request with custom headers), the browser first fires an OPTIONS preflight request. The server must respond with the allowed origin, methods, and headers. Only then does the browser fire the real request.

REST API CORS Configuration

In REST API you enable CORS on each resource. Amazon API Gateway auto-creates an OPTIONS method backed by a mock integration that returns the CORS headers:

• Access-Control-Allow-Origin: https://app.example.com (or *)
• Access-Control-Allow-Methods: GET, POST, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization, X-Api-Key
• Access-Control-Max-Age: 600 (cache the preflight for 10 minutes)

For Lambda proxy integrations, your Lambda must also return the Access-Control-Allow-Origin header on the real response — the mock integration only covers preflight.

HTTP API CORS Configuration

HTTP API exposes CORS as a first-class API-level setting (not per-resource). Configure allowed origins, methods, headers, and max age once, and Amazon API Gateway handles all preflight and response-header injection automatically, including for Lambda proxy responses. This is one of HTTP API's biggest quality-of-life wins over REST API.

Common CORS Error Patterns

• "CORS preflight failed" → OPTIONS method is missing or returning the wrong headers.
• "No 'Access-Control-Allow-Origin' header" on the real request → Lambda proxy isn't returning the header.
• "Credentials flag is true, but ACAO is '*'" → when sending cookies, the allow-origin must be the exact origin, not a wildcard.

AWS WAF Integration

AWS WAF attaches to REST API regional and edge-optimized endpoints (via CloudFront for edge-optimized). WAF evaluates inbound requests against a Web ACL containing managed rule groups (SQL injection, XSS, bot control) or custom rules. Matching requests are blocked, counted, or challenged before reaching Amazon API Gateway.

WAF does not currently support HTTP API directly. For HTTP API, front it with CloudFront and attach WAF to the CloudFront distribution.

WAF protects against:

• OWASP Top 10 attack patterns via AWS Managed Rules.
• Specific IP ranges via IP sets (allowlist/blocklist).
• Rate-based rules (block an IP that sends > N requests per 5-minute window — a per-IP throttle that complements usage-plan throttling).
• Geo restrictions by country.
• Bot management signals via AWS Managed Rules Bot Control.

Custom Domain Names and Endpoint Types

The default Amazon API Gateway URL looks like https://abcd1234.execute-api.us-east-1.amazonaws.com/prod/orders — useful for development, awful for production. Custom domain names let you expose https://api.example.com/orders instead.

Endpoint Types

Amazon API Gateway offers three endpoint types for REST API and two for HTTP API:

• Edge-Optimized (REST only) — the API is fronted automatically by a CloudFront distribution managed by Amazon API Gateway. Global clients enjoy lower latency via edge caching and connection termination at CloudFront PoPs. Choose when clients are spread worldwide.
• Regional — clients connect directly to the regional Amazon API Gateway endpoint. Lower per-request cost, fewer moving parts, and you can front with your own CloudFront if needed. Choose when clients are mostly in one Region, or when you want to bring your own CloudFront for finer control.
• Private (REST only) — the API is reachable only from VPCs via an Interface VPC Endpoint (AWS PrivateLink). No public access at all. Choose for internal enterprise APIs.

ACM Certificates — Region Matters

Amazon API Gateway requires an ACM-issued TLS certificate to serve a custom domain:

• Edge-optimized endpoints require the certificate in us-east-1 (because CloudFront always lives there).
• Regional endpoints require the certificate in the same Region as the API.

Importing a third-party certificate is supported but auto-renewal only works with ACM-issued certs.

Base Path Mapping

A single custom domain can route traffic to multiple APIs based on URL path prefix: api.example.com/orders → Orders API, api.example.com/users → Users API. Base path mappings are configured under the custom domain.

OpenAPI Import and Export

Amazon API Gateway natively imports and exports OpenAPI 3.0 (and Swagger 2.0) definitions. An OpenAPI file fully describes your API: resources, methods, models, security schemes, integration types, request/response mappings, and stage variables. Combined with AWS-specific x-amazon-apigateway-* extensions, an OpenAPI file can round-trip through the Amazon API Gateway console, AWS CLI (import-rest-api), or Infrastructure-as-Code (AWS SAM, CloudFormation, CDK, Terraform).

Common OpenAPI extensions you will see on DVA-C02:

• x-amazon-apigateway-integration — the integration (Lambda URI, HTTP URL, VTL templates).
• x-amazon-apigateway-request-validator — request validation behavior.
• x-amazon-apigateway-authorizer — authorizer configuration.
• x-amazon-apigateway-api-key-source — where the API key is read from.
• x-amazon-apigateway-binary-media-types — binary handling.

Exporting the current API as OpenAPI is handy for reviews, client SDK generation, and archiving before breaking changes. Use aws apigateway get-export --rest-api-id ... --stage-name prod --export-type oas30 out.json.

Observability — CloudWatch Metrics, Access Logs, and X-Ray

Amazon API Gateway emits CloudWatch metrics per API and stage:

• Count — number of requests.
• 4XXError / 5XXError — client vs server errors.
• Latency — full round-trip including backend.
• IntegrationLatency — backend-only latency.
• CacheHitCount / CacheMissCount — caching effectiveness.

Access logs can be enabled per stage and written to CloudWatch Logs or Kinesis Data Firehose in a custom JSON format using $context variables. Execution logs (per-request diagnostic trace) are separate and tied to a log level (INFO or ERROR).

AWS X-Ray tracing is supported for REST API and, since 2023, HTTP API. Enable active tracing on the stage; Amazon API Gateway adds a segment showing how long each step (authorizer, integration, mapping) took.

Amazon API Gateway Cheat Sheet for DVA-C02

Top 10 Amazon API Gateway Traps on DVA-C02

1. HTTP API does not support API keys or usage plans — pick REST API for monetization.
2. Lambda proxy vs Lambda non-proxy — proxy passes everything, non-proxy uses VTL.
3. API keys alone are not authentication — always pair with IAM, Cognito, or Lambda authorizer.
4. Canary deployments are REST API only — HTTP API has auto-deploy; use Lambda weighted aliases instead.
5. WAF attaches to REST API, not HTTP API — front HTTP API with CloudFront + WAF.
6. Edge-optimized certificates must be in us-east-1 — regional must be in the API's Region.
7. Authorizer cache persists after token revocation — TTL up to 3600 seconds means revoked tokens can keep working.
8. Account-level throttle is shared across all APIs — one noisy API can starve others; use stage-level throttles.
9. VPC Link REST API requires NLB — VPC Link v2 for HTTP API supports ALB/NLB/Cloud Map.
10. CORS preflight is a mock integration — Lambda proxy must still return Access-Control-Allow-Origin on the real response.

Practice Question Patterns for Amazon API Gateway

• API type selection: "Need real-time notifications to 10k connected clients" → WebSocket API.
• Authorizer selection: "Third-party JWT from Okta, need to cache auth decisions" → Lambda TOKEN authorizer with TTL.
• Integration selection: "Reach an ECS service inside a private VPC via an NLB" → REST API + VPC Link.
• Transformation: "Reshape the request body before invoking Lambda without changing the Lambda code" → Lambda non-proxy + VTL mapping template.
• Quota: "Different request limits per customer tier" → REST API + Usage Plans + API Keys.
• Safe rollout: "Deploy new version to 10% of traffic, monitor, then ramp" → Canary deployment on REST API stage.
• Performance: "Read-heavy endpoint causing Lambda cost to spike" → Enable method-level caching.
• Security: "Block OWASP injection attempts at the edge" → AWS WAF attached to REST API (or HTTP API via CloudFront).

FAQ — Amazon API Gateway Top Questions for DVA-C02

Q1: What is the difference between Lambda proxy and Lambda non-proxy integration in Amazon API Gateway?

Lambda proxy integration (AWS_PROXY) passes the entire HTTP request to Lambda as a JSON event and expects Lambda to return a JSON object in a specific shape ({statusCode, headers, body, isBase64Encoded}). No VTL mapping templates are involved. Lambda non-proxy (AWS, also called custom integration) uses VTL mapping templates on both request and response, letting you reshape the payload at the edge while keeping the Lambda function HTTP-agnostic. Use Lambda proxy for 95% of serverless apps — it is simpler and faster. Use Lambda non-proxy when the public API contract must stay stable while the Lambda signature evolves, or when per-status-code response shaping is required.

Q2: When should I choose Amazon API Gateway HTTP API over REST API?

Choose HTTP API when your workload is a straightforward Lambda or HTTP proxy backend with JWT-based authorization (typically Cognito or OIDC) and you do not need VTL mapping templates, API keys, usage plans, per-method caching, AWS WAF, private APIs, or request validation against JSON schema. HTTP API is roughly 70% cheaper per request than REST API and has lower latency, so it is the right default for new serverless APIs. Switch to REST API the moment a requirement in that "does not need" list surfaces — mixing HTTP API with per-customer quotas or VTL is not possible.

Q3: How do Amazon API Gateway usage plans and API keys enforce throttling and quota?

Usage plans are REST-API-only constructs that bind throttle (requests per second steady-state plus burst), quota (requests per day/week/month), and associated API stages. You create API keys (one per customer or tier), associate each key with a usage plan, and enforce API Key Required on each method. Clients pass the key in the x-api-key header. Amazon API Gateway matches the key to its plan and returns HTTP 429 when throttle or quota is exceeded. Remember API keys are not security — always combine them with an IAM, Cognito, or Lambda authorizer for authentication.

Q4: How does an Amazon API Gateway Lambda authorizer caching actually work?

Lambda authorizers (both TOKEN and REQUEST) support result caching with TTL from 0 (disabled) to 3600 seconds, default 300. Amazon API Gateway caches the returned IAM policy keyed on the identity source — the token for TOKEN type, or a developer-specified set of headers/query/stage variables for REQUEST type. When the cache hits, the authorizer Lambda is not invoked, saving latency and cost. The trade-off is that revoked tokens or changed permissions stay cached until TTL expires. Balance TTL against your security posture: 5 minutes is a common default, 1 minute for sensitive APIs, 0 for anything requiring immediate revocation.

Q5: What is the difference between a canary deployment and a stage in Amazon API Gateway?

A stage is a named deployment target (for example dev, qa, prod) that has its own URL, stage variables, throttle settings, caching, and logs. A canary is a second deployment attached to an existing stage that takes a configurable percentage of traffic, typically used to safely roll out a new version on top of the existing production stage. Canary traffic can have its own overriding stage variables (pointing at a new Lambda alias, for example) and emits separate CloudWatch metrics tagged with $context.canary. Canary is REST API only; for HTTP API use Lambda alias weighted routing to achieve similar effect.

Q6: What endpoint type should I choose — edge-optimized, regional, or private?

Choose edge-optimized for consumer-facing APIs with globally distributed users — Amazon API Gateway fronts the API with a managed CloudFront distribution so clients hit a nearby edge PoP. Choose regional when clients are concentrated in one Region, for B2B and inside-AWS integrations, or when you want to bring your own CloudFront with finer control. Choose private when the API must be reachable only from VPCs (typically internal enterprise APIs) — Amazon API Gateway exposes it via an Interface VPC Endpoint (PrivateLink) and no public DNS resolves. Remember edge-optimized ACM certificates must live in us-east-1; regional certificates live in the API's Region.

Q7: How do stage variables and mapping templates interact in Amazon API Gateway?

Stage variables are key-value pairs bound to a stage; mapping templates are VTL scripts that transform requests and responses in non-proxy integrations. They compose: a mapping template can reference $stageVariables.varName to inject per-stage values into the backend call. A common pattern is setting a stage variable lambdaAlias=LIVE on the prod stage and lambdaAlias=DEV on the dev stage, then having the integration URI reference $stageVariables.lambdaAlias. One API definition, deployed once, routes to different Lambda aliases depending on the stage. During canary deployments, canary-specific stage variables can override the base ones, enabling safe progressive rollouts without changing the API definition.

Q8: When should I integrate AWS WAF with Amazon API Gateway?

Integrate AWS WAF whenever the API faces the public internet and processes user-supplied data — which is virtually always. WAF managed rule groups block OWASP Top 10 attacks (SQL injection, XSS), bad bots, IP ranges known for abuse, and geo-restricted regions. Rate-based WAF rules complement usage plan throttling by limiting per-source-IP request rate to defeat brute-force and DDoS attempts at L7. WAF attaches directly to REST API (regional or edge-optimized). HTTP API does not support WAF directly, so front HTTP API with CloudFront and attach WAF to the CloudFront distribution instead. Cost is a few dollars per million requests plus the Web ACL hourly fee.

Further Reading

• Amazon API Gateway Developer Guide (all chapters)
• AWS Serverless Application Model (SAM) documentation for CloudFormation-based Amazon API Gateway deployment
• AWS re:Invent sessions SVS401 and API303 for advanced Amazon API Gateway patterns
• AWS Well-Architected Serverless Applications Lens
• AWS Whitepaper: Best Practices for Designing Amazon API Gateway Private APIs and Private Integrations

Master Amazon API Gateway — the REST vs HTTP vs WebSocket trade-offs, the six integration types, VTL mapping templates, the five authorization mechanisms with Lambda authorizer caching, usage plans with API keys, stage variables and canary deployments, the layered throttling model, method-level caching, CORS preflight handling, AWS WAF integration, custom domains across edge-optimized/regional/private endpoint types, and OpenAPI round-tripping — and the Amazon API Gateway questions on DVA-C02 transform from intimidating edge-case trivia into reliable scoring opportunities. Every serverless reference architecture that ships from AWS rides Amazon API Gateway at the edge, so the knowledge compounds well past exam day into everyday developer work. Good luck on your DVA-C02 Amazon API Gateway questions.