Cloud / Amazon API Gateway Interview questions

Amazon API Gateway is a fully managed AWS service for creating, publishing, securing, and monitoring APIs at any scale. It sits in front of your backend (Lambda, EC2, containers, or any HTTP endpoint) and acts as the single entry point for clients.

It handles the plumbing you would otherwise build yourself: request routing, authorization, throttling, caching, request/response transformation, and metrics. There are no servers to manage, and you pay per request.

• Supports REST, HTTP, and WebSocket APIs
• Integrates natively with Lambda, IAM, Cognito, CloudWatch, and WAF
• Scales automatically with traffic

API Gateway offers three API types, and picking the right one early saves rework later.

There was also the older concept of REST "private" and "regional" endpoints, but those are endpoint types, not API types.

A REST API can be deployed with one of three endpoint types, which decide where traffic enters AWS.

1. Edge-optimized - requests go through a CloudFront-managed distribution and enter AWS at the nearest edge location. Good for geographically spread clients.
2. Regional - requests hit the API directly in the Region. Best when clients are in the same Region, or when you want to attach your own CloudFront distribution.
3. Private - reachable only from inside a VPC through an interface VPC endpoint.

Edge-optimized is the default when creating a REST API in the console, but Regional is often the better choice for modern setups.

A stage is a named snapshot of your API that clients can actually call, such as dev, test, or prod. Creating an API alone exposes nothing; you deploy it to a stage.

Each stage has its own invoke URL, for example:

https://abc123.execute-api.us-east-1.amazonaws.com/prod

Settings like throttling, caching, logging, stage variables, and canary configuration are stored per stage, so you can run dev with debug logging and prod with caching on, using the same API definition.

A resource is a path in your API's URL tree, such as /orders or /orders/{orderId}. Curly braces mark a path parameter.

A method is an HTTP verb attached to a resource, for example GET /orders or POST /orders. Each method has its own configuration: authorization, request validation, integration, and responses.

So resources define where a request goes, and methods define what action is allowed there. Special cases exist too, like ANY (all verbs) and greedy path variables such as {proxy+}.

An integration tells API Gateway how to forward a request to the backend. REST APIs support five types:

In Lambda proxy integration, API Gateway passes the entire HTTP request (headers, query string, path parameters, body) to Lambda as a single event object. Your function then decides what to return.

The function must return JSON in a specific shape:

{
  "statusCode": 200,
  "headers": { "Content-Type": "application/json" },
  "body": "{\"ok\": true}",
  "isBase64Encoded": false
}

Note that body must be a string, not a JSON object. It is the simplest way to build a Lambda-backed API because no mapping templates are needed.

A mapping template transforms a request or response payload between the client's format and the backend's format. It is written in Velocity Template Language (VTL) and applies to non-proxy integrations.

For example, this template turns a query string into a JSON body for a backend:

{
  "userId": "$input.params('userId')",
  "source": "$context.identity.sourceIp"
}

Templates are selected by the request Content-Type. If none matches, the behavior depends on the passthrough setting: pass the body as-is, or reject with 415 Unsupported Media Type.

An API key is an alphanumeric string that identifies a client application. A usage plan defines what that client may do: throttle rate, burst, and a quota per day, week, or month.

You attach API stages to a usage plan, then associate keys with the plan. Requests must carry the key in the x-api-key header, and the method must have "API key required" enabled.

They work on REST APIs only; HTTP APIs do not support usage plans. Use them for metering and partner tiers, not as your main security control.

A Lambda authorizer (formerly custom authorizer) is a Lambda function that API Gateway calls before invoking the backend to decide whether a request is allowed. You use it for custom auth logic such as validating a third-party token or checking a database.

The function returns an IAM policy document with Allow or Deny on the requested resource, plus a principalId and an optional context map that is passed to the backend.

Results can be cached for up to one hour, which cuts latency and Lambda invocations for repeat callers.

A Cognito user pool authorizer lets API Gateway validate tokens issued by an Amazon Cognito user pool without any custom code. The client signs in with Cognito, receives a JWT, and sends it in the Authorization header.

API Gateway checks the token's signature and expiry. With an ID token, it can also require that the caller belongs to the pool; with an access token, you can require specific OAuth scopes on the method.

It is the quickest option when your users already live in Cognito. For other identity providers, use a Lambda authorizer or a JWT authorizer on an HTTP API.

Stage variables are name-value pairs attached to a stage that act like environment variables for your API configuration. You reference them as ${stageVariables.name}.

A common use is pointing each stage at a different backend without changing the API definition:

Integration URI: https://${stageVariables.host}/orders
Lambda: arn:aws:lambda:...:function:orders:${stageVariables.alias}

Set host=dev.example.com on dev and host=api.example.com on prod. Do not store secrets in them, since they are not encrypted.

API Gateway can cache endpoint responses for a stage so repeated identical requests are served from cache instead of hitting your backend. This lowers latency and backend load.

Key facts:

• Available on REST APIs only, enabled per stage
• Cache size ranges from 0.5 GB up to 237 GB
• Default TTL is 300 seconds; the maximum is 3600, and 0 disables caching
• Cache keys can include query strings, headers, or path parameters

You pay hourly for the cache capacity you provision, so it makes sense mainly for read-heavy, repeatable responses.

A custom domain name lets clients call your API at api.example.com instead of the generated execute-api URL. You attach an ACM certificate and create a DNS record (usually a Route 53 alias) pointing to the domain's target.

Then base path mappings (or API mappings for HTTP APIs) connect paths to specific APIs and stages, for example /v1 to the prod stage of one API and /v2 to another.

For an edge-optimized domain, the ACM certificate must be in us-east-1; for Regional domains, it must be in the same Region as the API.

Throttling limits how many requests per second API Gateway will accept, protecting your backend from spikes. When a client exceeds the limit, API Gateway rejects the excess with HTTP 429 Too Many Requests.

Limits are applied at several levels:

1. Account-level per Region (default 10,000 requests/second steady-state, 5,000 burst)
2. Per-stage or per-method settings
3. Per-client limits through usage plans

Clients should handle 429 with retries and exponential backoff.

A mock integration makes API Gateway generate the response itself, with no backend involved. You define the status code and body in the integration response mapping.

It is useful in three situations:

• Front-end teams need a working API before the backend exists
• Answering CORS preflight OPTIONS requests
• Testing gateway behavior such as auth and throttling in isolation

The request mapping template must return {"statusCode": 200} so API Gateway knows which integration response to use.

A WebSocket API keeps a persistent, two-way connection between client and server so either side can send messages at any time, without the client polling.

API Gateway manages connections and routes each incoming message to a backend (often Lambda) based on a route selection expression. Three special routes exist: $connect, $disconnect, and $default.

Typical use cases are chat apps, live scoreboards, collaborative editing, and push notifications. Connections idle out after 10 minutes and last at most 2 hours.

A private API is a REST API that can only be invoked from within your VPC (or connected networks) through an interface VPC endpoint for execute-api. It has no public internet exposure.

To make it work you need three things: the private endpoint type, an interface VPC endpoint in the calling VPC, and a resource policy that allows traffic from that endpoint or VPC.

Typical use: internal microservice APIs, or backends for internal tools reached over VPN or Direct Connect.

A VPC link lets API Gateway reach resources inside a VPC, such as services behind a load balancer, without exposing them publicly.

For REST APIs, a VPC link traditionally targets a Network Load Balancer. For HTTP APIs, VPC links (v2) can target an Application Load Balancer, an NLB, or AWS Cloud Map service instances.

You then create an HTTP or HTTP_PROXY integration whose connection type is VPC_LINK. Traffic stays on the AWS network and your backend can live in private subnets.

CORS lets a browser on one origin call your API on another. In API Gateway the setup differs by type.

Forgetting the headers on error responses is a common bug; the browser then shows a CORS error instead of the real 4xx or 5xx.

API Gateway reports to CloudWatch in three ways: metrics, access logs, and execution logs. You can also trace REST APIs with AWS X-Ray.

The metrics to watch first:

• Count - total requests
• 4XXError and 5XXError - client and server error counts
• Latency - total time from request received to response sent
• IntegrationLatency - time spent waiting on the backend
• CacheHitCount / CacheMissCount - cache effectiveness

Comparing Latency with IntegrationLatency shows quickly whether slowness is in the gateway or your backend.

Request validation lets API Gateway reject malformed requests before they reach your backend, saving Lambda invocations and backend load. It returns a 400 response when validation fails.

Two things can be checked on a REST API method:

1. Required query strings, headers, and path parameters
2. The request body against a model defined with JSON Schema

{
  "type": "object",
  "required": ["email"],
  "properties": { "email": { "type": "string" } }
}

It only checks structure and types, so business rules still belong in your code.

A canary release sends a small percentage of a stage's traffic to a new deployment while the rest continues to hit the current one. It is available for REST APIs.

The flow is straightforward:

1. Deploy the new version to the stage as a canary with, say, 10% traffic
2. Watch metrics and logs (canary stats are reported separately)
3. Promote the canary to 100%, or delete it to roll back

You can also override stage variables just for the canary, which is handy for pointing it at a new Lambda alias.

In a REST API, edits to resources, methods, or integrations are saved to a working copy that is not live. Callers only see what has been captured in a deployment associated with a stage.

So after changing a route or integration, you must create a new deployment for the stage to pick it up. The console has a "Deploy API" action; in CLI it is create-deployment. Infrastructure-as-code tools often need a trigger (like a hash) to force this.

HTTP APIs are different: they support auto-deploy on a stage, so changes go live automatically.

Both expose HTTP endpoints, but HTTP APIs are the newer, trimmed-down option built for lower cost and latency. REST APIs keep the deeper feature set.

Choose HTTP API for straightforward Lambda or HTTP proxying, and REST API when you need caching, WAF, usage plans, or request transformation.

The difference is how requests enter AWS before reaching your API.

Edge-optimized can cut connection setup time for far-away users, but Regional gives you more control, such as adding your own CloudFront rules or WAF at the edge.

With a proxy integration, API Gateway forwards the request as-is and returns whatever the backend sends. With a non-proxy (custom) integration, you configure how requests and responses are transformed.

Proxy is usually the default recommendation; use non-proxy when the backend cannot be changed.

Both are Lambda authorizers; they differ in what the function receives and what forms the cache key.

If your auth decision depends on more than one value, pick REQUEST. It is also required for WebSocket $connect authorizers.

Use IAM authorization when callers are AWS identities: other AWS services, EC2 or Lambda roles, or internal applications with AWS credentials. Clients sign requests with Signature Version 4 (SigV4), and API Gateway checks the IAM policy attached to the caller.

The caller needs an identity policy allowing execute-api:Invoke on the API's ARN:

{
  "Effect": "Allow",
  "Action": "execute-api:Invoke",
  "Resource": "arn:aws:execute-api:us-east-1:123456789012:abc123/prod/GET/orders"
}

It fits service-to-service calls well. It is a poor fit for public browser users, who do not hold AWS credentials.

API keys identify a client for metering; they do not authenticate a user. A key is a static string that can be copied from an app, logged, or leaked, and anyone holding it can call the API.

AWS says as much in its guidance: don't rely on keys for authorization. They are meant to work with usage plans for throttling and quotas.

For real security, combine them with an actual authorizer: IAM, Cognito, JWT, or a Lambda authorizer. Then the key handles quota and the authorizer handles identity.

API Gateway uses the token bucket algorithm. The bucket holds up to the burst number of tokens and refills at the rate (steady-state requests per second). Each request consumes a token; if the bucket is empty, the request gets a 429.

Limits are checked from most specific to least:

1. Per-client limits in a usage plan
2. Per-method limits on a stage
3. Per-stage/API default limits
4. The account-level Region limit

A method limit cannot exceed the account limit, so a noisy API in one stage can still starve others if you never set per-stage caps.

You can flush the entire stage cache from the console, or with the CLI flush-stage-cache command. This immediately empties every cached entry for that stage.

Clients can also request a single fresh response by sending the header Cache-Control: max-age=0. By default this is allowed to anyone, so it is safest to require authorization (an IAM permission called execute-api:InvalidateCache) or turn off the option.

Otherwise, entries simply expire when the TTL runs out.

A JWT authorizer validates JSON Web Tokens issued by an OpenID Connect or OAuth 2.0 provider, such as Cognito, Auth0, or Okta, with no Lambda function.

You configure an issuer URL and one or more audiences. For each request, API Gateway does the following:

1. Reads the token from the identity source (usually the Authorization header)
2. Verifies the signature against the issuer's public keys
3. Checks exp, iss, and aud or client_id
4. Optionally enforces route-level scopes

Valid claims are passed to the backend in the request context.

API Gateway responds with 502 Bad Gateway and a message like "Malformed Lambda proxy response". The function ran, but its output did not match the structure API Gateway expects.

Frequent causes:

• body returned as an object instead of a string
• statusCode missing or not an integer
• Returning plain text or nothing at all
• An unhandled exception, which produces a different 502 message

Check the function's CloudWatch logs first, and use the console Test feature to see the exact response API Gateway received.

A 504 means the backend did not respond before the integration timeout. For REST APIs the default (and historical maximum) is 29 seconds; HTTP APIs allow up to 30 seconds. Regional REST APIs can request a higher timeout through a quota increase, but that may lower your account throttle limit.

Common reasons:

• Slow database queries or downstream calls
• Lambda cold starts plus long processing
• A backend unreachable through a VPC link

Look at IntegrationLatency in CloudWatch. For long-running work, return 202 and process asynchronously, for example through SQS or Step Functions.

A 403 has several possible sources, so narrow it down by the error message in the response body.

Turn on execution logging for the stage; it shows whether the authorizer, policy, or key check failed.

A resource policy is a JSON policy attached to the API itself that says who may invoke it. For a private API it is mandatory in practice, because it decides which VPC endpoints or VPCs can get through.

{
  "Effect": "Deny",
  "Principal": "*",
  "Action": "execute-api:Invoke",
  "Resource": "execute-api:/*",
  "Condition": { "StringNotEquals": { "aws:SourceVpce": "vpce-0abc123" } }
}

Pair the Deny with an Allow, and every call not arriving via vpce-0abc123 is blocked. Resource policies can also allow other AWS accounts, or restrict by source IP on Regional APIs. They are supported on REST APIs.

You associate an AWS WAF web ACL with a REST API stage. WAF then inspects every request before API Gateway processes it and can block, allow, or count based on your rules.

Typical rules include managed rule groups for SQL injection and XSS, IP allow/deny lists, geo restrictions, and rate-based rules that block one IP sending too many requests.

HTTP APIs and WebSocket APIs do not support direct WAF association. For those, put CloudFront with WAF in front of the API.

With mutual TLS (mTLS), the client also presents a certificate, so both sides authenticate. It is configured on the custom domain, not the API.

1. Upload a truststore (a PEM file of trusted CA certificates) to S3
2. Enable mTLS on the custom domain and point it at the truststore
3. Clients connect with a certificate chained to a CA in that truststore

It needs a Regional custom domain and the default execute-api endpoint should be disabled, otherwise clients can bypass mTLS. It is common for B2B and IoT scenarios.

When a message arrives, API Gateway evaluates the API's route selection expression against it to pick a route. The most common expression is $request.body.action.

For example, with that expression, this message goes to the sendMessage route:

{ "action": "sendMessage", "text": "hello" }

If no route matches, the message goes to $default (if defined). Connection lifecycle uses the reserved $connect and $disconnect routes. Each route has its own integration, so different actions can hit different Lambdas.

Every connected client gets a connection ID, which you receive in the $connect event. Store it, for example in DynamoDB, then use the @connections management API to push data to it.

POST https://{api-id}.execute-api.{region}.amazonaws.com/{stage}/@connections/{connectionId}

In code you would normally use the SDK's PostToConnection call, signed with IAM. Other operations exist too: GetConnection and DeleteConnection. A 410 Gone response means the client disconnected, so remove the stale ID from your table.

API Gateway has no single built-in versioning feature, so teams pick a strategy that fits.

Whichever you choose, keep older versions running until clients migrate, and use canary releases for minor changes.

You can define an API in OpenAPI 3 (with x-amazon-apigateway-* extensions) or model it directly, then deploy through CloudFormation, AWS SAM, CDK, or Terraform.

In SAM, a Lambda-backed HTTP API can be just a few lines:

Events:
  GetOrders:
    Type: HttpApi
    Properties:
      Path: /orders
      Method: get

Watch out for REST APIs in raw CloudFormation: an AWS::ApiGateway::Deployment won't redeploy when methods change unless something in it changes, so add a hash or use SAM/CDK, which handle it for you.

API Gateway treats payloads as text by default, so binary content such as images or PDFs needs explicit setup.

1. Add the content type (for example image/png or application/pdf) to the API's binary media types list
2. With Lambda proxy, return the body Base64-encoded and set isBase64Encoded: true
3. Ensure the client's Accept header matches a configured binary type when returning binary

The payload size limit is 10 MB for REST and HTTP APIs, so large uploads should go directly to S3 using pre-signed URLs instead.

You can skip Lambda and let API Gateway call an AWS service directly, using an AWS service integration with an IAM role that allows the action.

For SQS, a REST API method can use a POST to SendMessage with a request mapping template:

Action=SendMessage&MessageBody=$util.urlEncode($input.body)

Set the Content-Type to application/x-www-form-urlencoded and give the execution role sqs:SendMessage. This cuts cost and latency. HTTP APIs offer first-class integrations for SQS, EventBridge, Step Functions, and Kinesis, with less mapping work.

Start by measuring: CloudWatch shows which APIs and routes carry the traffic and where latency comes from.

• Use HTTP APIs when you don't need REST-only features; the per-request price is much lower
• Enable caching on read-heavy REST endpoints with sensible TTLs
• Cache authorizer results to avoid an extra Lambda call per request
• Validate requests at the gateway so bad calls never invoke the backend
• Enable compression on REST APIs to shrink large responses
• Use direct integrations instead of a pass-through Lambda
• Reduce cold starts with provisioned concurrency for latency-critical functions

Also remove unused stages and caches, since a provisioned cache bills hourly even when idle.

API Gateway is Regional, so multi-Region resilience means deploying the same API in two Regions and steering traffic between them.

1. Deploy identical APIs and backends (via IaC) in Region A and Region B
2. Create a Regional custom domain in each Region with the same name and an ACM certificate per Region
3. Use Route 53 failover or latency routing with health checks pointing at each Regional domain
4. Replicate data stores, for example DynamoDB global tables

Test the failover regularly. The gateway layer is easy to duplicate; stateful backends are usually the harder part.

When a client calls a REST API, the request passes through a fixed pipeline. Knowing the order helps you place logic and debug failures.

flowchart LR
  A["Client request"] --> B["WAF check"]
  B --> C["Authorization: IAM / Cognito / Lambda"]
  C --> D["Throttling and usage plan"]
  D --> E{Cache hit?}
  E -- Yes --> J["Return cached response"]
  E -- No --> F["Request validation and mapping"]
  F --> G["Integration call to backend"]
  G --> H["Integration response mapping"]
  H --> I["Return to client"]

Failures map to stages: 403 usually comes from WAF or auth, 429 from throttling, 400 from validation, and 502/504 from the integration. A cache hit skips the backend entirely, which is why it improves latency so much.

The authorizer returns an IAM policy, and API Gateway caches that whole policy against the token. If the policy allowed only the specific method ARN of the first call, later calls with the same token to a different route are checked against that cached policy and get denied.

Two common fixes:

1. Return a wildcard resource, such as arn:aws:execute-api:region:acct:api-id/stage/*/*, when the same token grants access to many routes
2. Set the cache TTL to 0 if the decision truly differs per route, or use a REQUEST authorizer whose identity sources include the path

Be careful with wildcards: they must match your real permission model, or you will over-grant.

Limits matter for design decisions, and many can be raised through Service Quotas. These are typical default values; confirm current numbers in the AWS documentation before relying on them.

The payload and timeout limits are the ones that most often force an architecture change, such as asynchronous processing or S3 pre-signed uploads.