Amazon API Gateway

What API Gateway is

API Gateway is a fully managed service for creating, publishing, and securing HTTP APIs at any scale. You define routes — a method plus a path — point each one at an integration (most commonly a Lambda function, but also another AWS service or an HTTP endpoint), and API Gateway hands you a public HTTPS URL that scales on its own and bills per request. It handles the tedious parts — HTTPS, throttling, auth, request/response mapping — so you never run a web server just to expose an API.

It’s the serverless equivalent of what an Application Load Balancer is for an EC2 fleet: the thing the outside world talks to, sitting in front of compute with no public endpoint of its own. Design Beaver models API Gateway as a regional, API-accessed service rather than something that sits inside a VPC subnet, and validates as you draw which services it can route to and what each of those connections needs to be correct.

When to use API Gateway (and when not to)

Reach for API Gateway when you want a managed HTTPS endpoint without running a server yourself, when the backend is Lambda, or when you need API-management features. The canonical pairing is API Gateway → Lambda → a database: API Gateway receives the request, Lambda runs the logic, the database stores the data. A Lambda function can’t receive an HTTP request by itself — it has to be invoked — so API Gateway (or a Lambda Function URL) is what turns a function into an API. And if you need rate limiting, API keys and usage plans, request validation, or per-route authorizers, those are built in.

Don’t reach for it for a long-running EC2 or container web tier serving a public site — an ALB, optionally behind CloudFront, is the more typical and cheaper front door, unless you specifically want API Gateway’s management features. It’s also the wrong tool for purely static content with no API logic (that’s CloudFront in front of S3) and for very high, steady request volume where the per-request price dominates — compare against an ALB-fronted compute tier at sustained load.

Variants: API type and endpoint type

API Gateway’s real choice point isn’t a “size” — it’s which type of API you build, and for REST APIs, which endpoint type serves it.

API Gateway pricing

You pay per request — per API call received — with REST APIs priced higher than HTTP APIs for the same call, plus data transfer out and, for REST APIs, optional response caching on top. The biggest lever is picking an HTTP API over a REST API when you don’t need REST’s extras.

How API Gateway connects to other services

API Gateway is rarely a lone box — it’s a front door, and each edge behind it has a requirement that makes it actually function: the IAM to invoke Lambda, the mapping templates for a direct service integration, the VPC Link to reach a private backend. Design Beaver models each of these connections, so it knows what API Gateway can route to and what that connection needs to be correct.

• →Lambda

  Lambda proxy integration — API Gateway passes the full request to a Lambda function and returns its response. The standard serverless API backend and the core of a serverless CRUD API.

• →DynamoDBsecurity

  Direct AWS service integration — API Gateway maps HTTP methods straight onto DynamoDB actions (GetItem/PutItem/Query/etc.) with no Lambda in between, for a simple CRUD passthrough

  IAM:dynamodb:GetItemdynamodb:PutItemdynamodb:Querydynamodb:UpdateItemdynamodb:DeleteItem

• →EC2

  Expose an EC2-hosted backend over a managed API — either an HTTP integration to a public endpoint, or a private integration via a VPC Link so API Gateway can reach instances in private subnets

• →ECS

  Expose a containerized ECS/Fargate backend over a managed API — API Gateway reaches the service through a VPC Link into the load balancer that fronts the tasks, so the tasks can stay in private subnets

• ←Route 53

  Route 53 alias record points a custom domain at the API's custom domain name, so clients call api.example.com instead of the default execute-api URL

• ←CloudFront

  CloudFront uses a Regional API Gateway endpoint as a custom origin, adding edge caching, a custom domain, and WAF in front of the API

• →Step Functionssecurity

  Direct AWS service integration — an API method starts a Step Functions execution (StartExecution for a Standard workflow, or StartSyncExecution for an Express workflow when the caller needs the result back synchronously), turning an HTTP request into a workflow run with no Lambda in between

  IAM:states:StartExecutionstates:StartSyncExecution

What API Gateway can’t connect to

Some edges look reasonable on a canvas but don’t exist in AWS. Design Beaver flags them instead of letting you draw a diagram that can’t be built.

• ✕RDS

  API Gateway integrates over HTTP or with AWS service APIs via mapping templates — RDS speaks a database wire protocol with no HTTP interface, so it can't be an integration target directly. Put a Lambda function (or an EC2/container app) between API Gateway and RDS.

Anti-patterns Design Beaver catches

These are the API Gateway mistakes that pass a diagram review but cost you later — the ones the validation engine flags as you draw.

Gotchas that bite in production

• A Lambda function has no HTTP endpoint on its own. If you’re building an API on Lambda, you need something in front — API Gateway, a Lambda Function URL, or an ALB. API Gateway is the default because it brings routing, auth, and throttling with it.
• Don’t double up CloudFront on an edge-optimized endpoint. Edge-optimized API Gateway endpoints already run through an AWS-managed CloudFront distribution. If you want your own CloudFront in front, switch the API to a Regional endpoint and use that as the origin.
• Direct DynamoDB integration is a trap past the simple case. Mapping-template (VTL) logic is hard to test and hard to maintain. It pays off only for thin passthrough CRUD; anything with validation or multi-step writes belongs in a Lambda function.
• EC2 isn’t a direct integration target. Front the instances with a load balancer and connect API Gateway through a VPC Link — a Network Load Balancer for a REST API private integration, an ALB or NLB for an HTTP API — or point an HTTP integration at a public endpoint.
• The free tier is 12-month, not Always Free. Unlike Lambda and DynamoDB, which have Always-Free allowances, API Gateway’s free tier expires 12 months after account creation.

Further reading

• Official AWS documentation
• Why we built a validation engine