Amazon API Gateway

What it is

Amazon API (Application programming interface)A defined way for one program to ask another for data or actions, such as a set of HTTPS requests and responses. Every AWS service is controlled through its API, which the console, the CLI, and the SDKs call for you.Glossary entry Gateway is a fully managed service for creating, publishing, securing, and monitoring APIs at any scale. It is the front door to your back end: clients call an API VPC endpointA private connection from a VPC to an AWS service or another endpoint service without crossing the internet. Gateway endpoints, for Amazon S3 and DynamoDB, are route table targets; interface endpoints are network interfaces that use AWS PrivateLink.Glossary entry, and API Gateway authenticates the request, applies ThrottlingLimiting how many requests a client can make in a period. A throttled request is rejected, often with HTTP status 429 or a throttling error, and should be retried later with backoff.Glossary entry, and passes it to an integration such as a Lambda function, an HTTP (Hypertext Transfer Protocol)The protocol that web browsers and APIs use to send requests, such as GET and POST, and receive responses. On its own it is not encrypted; HTTPS adds TLS.Glossary entry endpoint, or another AWS service.

It is a core part of serverless architectures (API Gateway, Lambda, and DynamoDB), and you pay only for the API calls it receives. Choose it when a question asks for a managed way to expose a REST (Representational state transfer)A style of web API in which resources are named by URLs and handled with standard HTTP methods, such as GET, PUT, and DELETE, and the server keeps no session state between requests. Amazon API Gateway builds REST APIs.Glossary entry or real-time API, protect it, and scale it without servers.

API types

Type	What it is for	Notes
REST API	Full-featured request and response APIs	Supports API keys and usage plans, per-client throttling, request validation, caching, AWS WAF, and private endpoints
HTTP API	Simpler, lower-cost request and response APIs	Minimal features, lower price; JWT (JSON Web Token)A compact, signed token that carries claims as JSON, such as who the user is and when the token expires. Amazon Cognito issues JWTs, and Amazon API Gateway can check them before passing a request to the backend.Glossary entry authorizers (for example Amazon Cognito) and Lambda authorizers
WebSocket API	Two-way, StatefulKeeping track of earlier requests or connections. A stateful firewall, such as a security group, remembers allowed connections and lets their return traffic back in automatically.Glossary entry communication	Clients keep a connection open, and the back end pushes messages to them through the `@connections` API: chat, live dashboards, games

REST APIs and HTTP APIs are both RESTful products. Choose REST APIs when you need API keys, per-client throttling, request validation, AWS WAF, or private endpoints; otherwise HTTP APIs cost less. Other REST-only features are caching, usage plans, request body transformation, canary releases, X-Ray tracing, and response streaming; when a requirement names one of them, an HTTP API can't meet it.

Endpoint types (REST APIs)

REST APIs offer three endpoint types; HTTP APIs support only Regional endpoints.

Edge-optimized (the default): requests go through the nearest CloudFront point of presence, which helps geographically spread clients. API Gateway manages that distribution: you can't configure it to cache responses, and putting your own distribution in front of an edge-optimized API adds a second CloudFront layer.
Regional: for clients in the same AWS RegionA separate geographic area where AWS runs its services, such as us-east-1 in Northern Virginia, made up of several Availability Zones. Most resources live in one Region; you choose Regions for latency, data residency, and the services you need.Glossary entry, or when you put your own CloudFront distribution in front. Use the same custom domain in several Regions with Route 53 LatencyThe time between sending a request and receiving the response, usually measured in milliseconds. Distance and processing add to it; caching and serving users from nearby locations reduce it.Glossary entry-based routing for multi-Region APIs. AWS Global Accelerator can't use an API as an endpoint (its endpoints are load balancers, EC2 instances, and Elastic IP (Internet Protocol)The protocol that addresses and routes packets between networks. Each device has an IP address: IPv4 addresses look like 192.0.2.1, and IPv6 addresses are longer, like 2001:db8::1.Glossary entry addresses).
Private: reachable only from inside a VPC, through an interface VPC endpoint (AWS PrivateLink), and controlled with a resource policy.

API Gateway endpoint types. Clients worldwide reach an edge-optimized API through a CloudFront distribution that API Gateway manages. Clients in the same Region call a Regional API directly. An application in a VPC reaches a private API through an interface VPC endpoint.

Concepts

Integrations: Lambda (proxy or custom), HTTP endpoints, AWS service actions (for example, writing straight to SQS, Kinesis, or Step Functions without a Lambda function), mock responses, and VPC links to private resources behind a Network Load Balancer or Application Load Balancer.
Stages (such as dev and prod) are deployed snapshots of an API, each with its own settings, variables, and URL. Stage variables are name-value pairs per stage that you can use in integration URIs, Lambda function ARN (Amazon Resource Name)The unique identifier of an AWS resource, in the form arn:partition:service:region:account-id:resource. IAM policies use ARNs to name the resources they allow or deny.Glossary entry, and mapping templates, so one API definition calls a different back end from each stage, for example the matching Lambda alias (grant API Gateway permission to invoke each alias). A canary release sends a small percentage of a stage's traffic to a new deployment before you promote it.
Custom domain names with certificates from AWS Certificate Manager.
CORS settings let browsers call the API from another domain.

Security, resilience, performance, and cost

Security

Authorization options:
- IAM (Signature Version 4) for AWS PrincipalA person or workload that can make requests to AWS, such as an IAM user, a role session, the root user, a federated user, or an AWS service. Resource-based policies name the principals they allow.Glossary entry and service-to-service calls, with no tokens or secrets to manage. For a caller in another account, both the caller's IAM policy and the API's resource policy must allow execute-api:Invoke; in the same account, either one is enough.
- Amazon Cognito user pools for signed-in app users: API Gateway validates the user pool token, so unauthenticated requests never reach the back end.
- Lambda authorizers for custom logic, such as third-party tokens. They come in TOKEN (one bearer token from a header) and REQUEST (headers, query strings, stage variables, and context) types. API Gateway can cache the returned policy for a TTL (Time to live)How long something stays valid before it expires. A DNS record or cached item can be reused until its TTL runs out, then is fetched again; in DynamoDB, a TTL attribute deletes items after a set time.Glossary entry, keyed by the token or identity sources, so repeated calls don't invoke the authorizer or the identity provider each time.
- On HTTP APIs, JWT authorizers.
Resource policies allow or deny calls from specific IP addresses, VPC endpoints, or AWS accounts.
API keys are not a security mechanism. Use them with usage plans to identify and meter clients, and use IAM, Cognito, or a Lambda authorizer for authentication.
AWS WAF protects REST APIs from common exploits such as SQL injectionAn attack that slips SQL code into form fields or parameters so that an application runs it against its database, for example to read or delete data. Parameterized queries prevent it, and AWS WAF can block common patterns.Glossary entry and XSS (Cross-site scripting)An attack that injects malicious script into a web page so that it runs in other users' browsers, where it can steal their session or data. AWS WAF has rules that match common XSS patterns in requests.Glossary entry, and can rate-limit by IP. Mutual TLS (Transport Layer Security)The protocol that encrypts traffic between a client and a server and lets the server prove its identity with a certificate. It replaced SSL, though the older name is still common; HTTPS is HTTP over TLS.Glossary entry is available on Regional custom domains (REST and HTTP APIs, not private APIs); disable the default execute-api endpoint so clients can't bypass it.

Resilience

API Gateway is a managed Regional service. For multi-Region resilience, deploy Regional APIs in two Regions behind Route 53.

Performance

Throttling uses a token bucket. The account default is 10,000 requests per second per Region, with a burst of 5,000 (2,500 and 1,250 in some newer Regions), shared by REST, HTTP, and WebSocket APIs; you can request an increase. Callers over the limit get 429 Too Many Requests. You can set lower limits for a stage and override them for individual methods, for example to cap one expensive method across all callers and protect its back end. Limits per client come from usage plans, which apply per API key, so they can't cap anonymous traffic.
Caching (REST APIs) stores responses per stage. The default TTL is 300 seconds and the maximum is 3,600 seconds; a TTL of 0 turns caching off. Only GET methods are cached by default, and you choose request parameters (path, query string, or header) as cache keys so each value is cached separately.
Integration timeout is 50 milliseconds to 29 seconds. For Regional and private REST APIs you can raise it above 29 seconds, which may require lowering the account's throttle quota; edge-optimized APIs can't. HTTP APIs have a fixed maximum of 30 seconds. For long-running work, return quickly and process asynchronously, for example through SQS or Step Functions.
The maximum payload size is 10 MB for REST and HTTP APIs, and it can't be raised. For large uploads, have the API return an S3 Presigned URLA URL that lets anyone who has it download or upload one specific S3 object for a limited time, using the permissions of the identity that created it.Glossary entry so the client uploads directly to a private bucket, keeping API Gateway and Lambda out of the data path.
Response streaming (REST APIs, Lambda proxy and HTTP proxy integrations) sends the response as it is produced, for up to 15 minutes, which exceeds the 10 MB and 29-second limits. It doesn't work with caching, and idle streams time out, so work that runs longer or returns nothing until the end still needs an asynchronous design.

Cost

Pay per API call received and for data transfer out. WebSocket APIs are charged per message and per connection minute. Caching is billed by the hour for the cache size you choose.
HTTP APIs cost less than REST APIs.
The free tier includes 1 million REST API calls, 1 million HTTP API calls, and 1 million WebSocket messages with 750,000 connection minutes per month for 12 months.

Monitoring

CloudWatch metrics: count, latency, integration latency, 4XX and 5XX errors, cache hits and misses.
Execution logs record how API Gateway processed requests. Access logs record who called the API, in a format you choose.
AWS X-Ray tracing for REST APIs, and CloudTrail for management API calls.

API Gateway or another option?

If the requirement is	Choose
Managed REST API in front of Lambda, with auth and throttling	API Gateway REST or HTTP API
Lowest-cost simple API with JWT auth	API Gateway HTTP API
Real-time two-way messages with clients	API Gateway WebSocket API
Managed GraphQL API	AWS AppSync
Distribute HTTP traffic across EC2 instances or containers	Application Load Balancer
A single HTTPS (HTTP Secure)HTTP sent over a TLS-encrypted connection, so that requests and responses cannot be read or changed on the way, and the server proves its identity with a certificate.Glossary entry endpoint for one Lambda function, no API features	Lambda function URL
Clients upload files larger than 10 MB	S3 presigned URL returned by the API

Reverse mindmap: when the question points here

Is it Amazon API Gateway?

Yes, when the question says
- Expose Lambda functions as a REST API leads to API Gateway
- Serverless API with throttling and authorization leads to API Gateway
- Real-time chat or push to clients leads to WebSocket API
Choose the setup
- Cheapest simple API leads to HTTP API
- API keys, usage plans, caching, or WAF leads to REST API
- Clients all over the world leads to Edge-optimized endpoint
- Only callable from inside a VPC leads to Private API with interface endpoint
- Send requests straight to SQS or Step Functions leads to AWS service integration
- Reach a private load balancer in a VPC leads to VPC link
- Same API definition, different back end per stage leads to Stage variables
- Your own CloudFront distribution in front leads to Regional endpoint
Secure it
- Signed-in app users leads to Cognito user pool authorizer
- Custom or third-party tokens leads to Lambda authorizer
- AWS principals and services leads to IAM authorization
- Block SQL injection leads to AWS WAF
- Allow only certain IPs or accounts leads to Resource policy
- IAM caller in another account leads to Caller's IAM policy and resource policy both allow
Run it well
- Meter and limit each customer leads to Usage plans with API keys
- Too many requests, 429 errors leads to Throttling limits
- Protect one expensive method's back end leads to Method-level throttling
- Repeated identical requests leads to Stage caching
- Uploads over 10 MB leads to S3 presigned URL
- Stream a large or slow response leads to Response streaming
- Test a new version on a few users leads to Canary release
No, when the question says
- GraphQL leads to AppSync
- Load balance EC2 targets leads to ALB
- Global Accelerator endpoint leads to not supported for API Gateway

Key takeaways

API Gateway is the managed front door for REST, HTTP, and WebSocket APIs.
REST APIs have the most features (API keys, usage plans, caching, WAF, private endpoints); HTTP APIs are cheaper and simpler; WebSocket APIs are two-way.
Endpoints: edge-optimized (default, through CloudFront), Regional, or private (VPC only).
Authorize with IAM, Cognito user pools, or Lambda authorizers; API keys only identify and meter clients.
Default throttling is 10,000 requests per second with a 5,000 burst, returning 429 when exceeded; cache TTL defaults to 300 seconds.
The integration timeout is up to 29 seconds by default, and the payload limit is 10 MB and can't be raised; use S3 presigned URLs for large uploads.
Cross-account IAM authorization needs both the caller's IAM policy and the API's resource policy to allow the call.