What Is Amazon API Gateway? REST, HTTP and WebSocket APIs

Amazon API Gateway is a managed service that receives HTTPS requests and forwards them to a backend: a Lambda function, an HTTP endpoint, a service behind a VPC link, or an AWS API such as SQS or DynamoDB. It handles TLS, routing, authorization, throttling and, depending on the API type, validation, caching and API keys. Lambda functions have no HTTP listener of their own, and API Gateway or a Function URL is how most Lambda backends get one.

This guide covers the three API types, how integrations and authorizers work, the limits that shape designs, pricing, and when a backend is better off without it.

Amazon API Gateway at a glance

How requests flow

A client calls the API's URL, or a custom domain mapped to it. API Gateway matches the method and path to a route, runs the authorizer if one is configured, applies throttling, and passes the request to the integration. With a Lambda proxy integration, the whole request arrives as a JSON event and the function returns the status code, headers and body. With an HTTP proxy integration, the request is forwarded to another HTTP endpoint, and a VPC link reaches private Application or Network Load Balancers or Cloud Map services inside a VPC.

REST APIs are deployed to stages such as dev and prod, each with its own settings and URL. HTTP APIs can deploy automatically on every change. WebSocket APIs route messages by a field in the message body to routes such as $connect, $disconnect and custom actions, and the backend sends messages back to clients through the connection management API.

Authorizers and throttling

Authorization runs before the backend is invoked, in one of three forms: IAM authorization checks SigV4-signed requests from AWS principals, JWT authorizers on HTTP APIs validate tokens from Cognito or another OIDC provider, and Lambda authorizers run your own function and can cache the result per token.

Throttling applies at the account level per region, with per-stage and per-route limits on top, and REST API usage plans set rate limits and quotas per API key. Requests above the limits get a 429 response before reaching the backend, which protects Lambda concurrency and databases behind it.

Limits that shape designs

API Gateway quotas affect architecture more than features do, starting with the integration timeout. It defaults to 29 seconds, so long-running work has to be queued and polled for or returned asynchronously; REST APIs can request a higher timeout for regional and private endpoints, at the cost of throttle capacity. The payload limit is 10 MB, which pushes file uploads to presigned S3 URLs. WebSocket connections last at most two hours and disconnect after ten minutes idle.

Pricing

Both HTTP and REST APIs are billed per million requests, with HTTP APIs priced well below REST APIs, plus data transfer out. REST API caching is billed per hour by cache size, and WebSocket APIs bill per message and per connection minute. The API Gateway pricing page lists rates per region. At high request volumes the per-request charge becomes noticeable compared with a load balancer's hourly charge.

API Gateway vs Application Load Balancer

For containers on ECS, Fargate or EKS, an Application Load Balancer is the usual front door. It routes by host and path, terminates TLS with ACM certificates, health-checks targets and bills per hour and per load balancer capacity unit, without per-request pricing or a 29 second cap. It has no API keys, usage plans or request validation, and those move into the application or a WAF. API Gateway fits Lambda backends and APIs sold to third parties with keys and quotas; an ALB fits container backends.

API gateway features in the application with Encore

Encore combines an open source infrastructure SDK with a platform that provisions and deploys into your own AWS or GCP account. For TypeScript and Go it is a backend framework with built-in infrastructure, and its API gateway is part of the application: endpoints, their request and response types and the auth handler are declared in code, and the gateway routes requests, validates them against the types and calls the auth handler before any endpoint marked auth: true:

import { api, APIError, Gateway, Header } from "encore.dev/api";
import { authHandler } from "encore.dev/auth";
import { secret } from "encore.dev/config";

const apiToken = secret("ApiToken");

interface AuthParams {
  authorization: Header<"Authorization">;
}

interface AuthData {
  userID: string;
}

// Runs before every endpoint with auth: true, like an authorizer.
export const auth = authHandler<AuthParams, AuthData>(async (params) => {
  if (params.authorization !== `Bearer ${apiToken()}`) {
    throw APIError.unauthenticated("invalid token");
  }
  return { userID: "service-client" };
});

export const gateway = new Gateway({ authHandler: auth });

interface Order {
  id: string;
  total: number;
}

// The route, method, path parameter and response type come from the code.
export const getOrder = api(
  { expose: true, auth: true, method: "GET", path: "/orders/:id" },
  async ({ id }: { id: string }): Promise<Order> => {
    return { id, total: 42 };
  },
);

Requests that do not match the declared types are rejected before the handler runs, as described in defining APIs, and middleware covers cross-cutting concerns such as rate limiting. encore run runs the same gateway locally, so authorization and routing are tested on a laptop instead of in a deployed stage. On AWS, Encore runs the services on Fargate or EKS behind an Application Load Balancer with no per-request gateway charge or 29 second limit, and it provisions an IAM role for the service, per the AWS infrastructure docs.

Best fit: teams building container backends who want routing, validation and authentication defined in the application code and testable locally, rather than configured in a separate API Gateway.

When to use API Gateway

Use API Gateway in front of Lambda functions, for APIs offered to external developers with keys, quotas and usage plans, for WebSocket APIs backed by Lambda, and when you want AWS-managed WAF, caching or private endpoints. For container backends with internal clients, a load balancer and authentication in the application usually cost less and remove the timeout and payload limits.

Related guides

• What is AWS Lambda?
• API gateways for microservices
• Lambda vs Fargate
• What is Amazon EventBridge?
• Serverless vs containers