Home › AWS › AWS data services › API Gateway

AWS data services · Query, warehouse and APIs · about 12 min read

Amazon API Gateway (REST, HTTP, WebSocket)

A managed front door for APIs: REST and HTTP APIs answer requests, WebSocket APIs keep a live line open to push changes to screens.

RoleQuery, warehouse and APIs
StatusGenerally available (REST, HTTP and WebSocket APIs)
Verdict on this sitePursue
AzureAzure API Management; Azure Web PubSub or SignalR for push
Google CloudAPI Gateway or Apigee; no managed WebSocket gateway (use Cloud Run)
Databricksnone: Databricks Apps can serve a small API or server-sent events, and SQL Statement Execution API answers queries
Open sourceKong, NGINX, Envoy; Socket.IO for push
Verdict: Pursue. The WebSocket API is how the fast lane pushes changes to the live plant board: a new screen gets a snapshot from DynamoDB, then only changes, at most one update a second per widget. Use HTTP or REST APIs only for the few small read APIs the platform must expose; analytics questions go to Databricks SQL, not through a Lambda behind a gateway.

In plain words

What it is

An API, short for application programming interface, is a door that one program uses to ask another program for something. API Gateway is a managed door. You describe the routes, for example GET /presses/{id}/status, and say what should answer each route: an AWS Lambda function (a small piece of code that AWS runs on demand), a service inside your private network, or another AWS service. API Gateway then handles the parts every door needs: checking who is calling, limiting how fast they may call, logging each call and scaling with traffic. You never run a server for it.

It comes in three kinds. A REST API is the older, fuller kind with request validation, API keys, usage plans, caching and private endpoints. An HTTP API is a lighter, cheaper kind for simple proxies with JSON Web Token sign-in. A WebSocket API is different in shape: instead of one question and one answer, the browser opens a connection and keeps it open, so the server can send messages whenever something changes. That last kind is the one this site cares about most.

A concrete example from a tyre plant. Each curing press sends temperature and pressure readings every second. Operators watch a live board on a wall screen. When a press drifts above its pressure limit, the board must turn red within a few seconds, without anyone pressing refresh. The browser holds a WebSocket connection to API Gateway. When the fast lane writes a changed value for press 14 into DynamoDB, a Lambda function reads that change and posts a short message to every connection that is watching press 14. The screen updates within about a second.

API Gateway does not store data, does not run queries and does not decide who should get which message. It knows connections by an ID, and your code keeps the list of who is watching what. That split is simple once you see it, and most production problems come from forgetting it.

A switchboard operator who keeps every caller's line open and patches through a message the moment your code hands one over, but keeps no notes of what was said.

Big picture

Where it fits

SourcesMove inStreamStoreProcessServeUseAcross everything: catalog · security · orchestration · observability and cost · infrastructure as codegets data fromhands data toDynamoDB StreamsLambdaBrowsers and plant screensAPI GatewayQuery, warehouse and APIsLive plant board in the browserLambdaOperator and supervisor screens

The lit lane is where API Gateway works. Boxes on the left feed it; boxes on the right use what it produces.

In the reference platform API Gateway sits at the very end of the fast lane, the seconds-level path for alerts. Readings arrive from plants through IoT Core onto Kinesis Data Streams, the stream belt. Managed Service for Apache Flink computes one-minute windows and limit breaches and writes only the values that changed into DynamoDB, the live store, which keeps the latest value per press plus 48 hours of history that expires on its own. DynamoDB Streams emits each change, a Lambda function reads it, and that function calls the WebSocket API's connection endpoint to push the change to the browsers watching that press.

When a new screen connects, it first reads a snapshot from DynamoDB, then receives only changes. The push function batches so that each widget gets at most one update a second; anything faster is noise to a human and only adds cost. AppSync Events is the managed alternative for this push job, to be tested in the physical design step.

The platform lane, where Databricks builds bronze, silver and gold every fifteen minutes, does not use API Gateway at all. Reports and questions go to Databricks SQL warehouses, AI/BI dashboards and Genie. A small HTTP API may still appear for a narrow operational need, such as a plant system asking for the current recipe limits, but it should read a prepared table or the live store, never run heavy SQL inside a Lambda function.

How it works

The ideas you need

IdeaWhat it means
REST APIThe fuller API type: request validation, API keys and usage plans, response caching, private endpoints inside a VPC, and AWS WAF in front.
HTTP APIA lighter, cheaper API type for proxying to Lambda or HTTP services, with built-in JSON Web Token sign-in but fewer features than REST.
WebSocket APIAn API that keeps a two-way connection open so the server can send messages to the client at any time, without the client asking.
RouteThe rule that says which code handles a request or message. WebSocket APIs have the special routes $connect, $disconnect and $default.
Connection IDThe identifier API Gateway gives each open WebSocket. Your code stores it and uses it to send messages to that one client.
@connections callbackThe management endpoint your code calls with a connection ID to post a message to that client, check it or close it.
IntegrationWhat answers a route: a Lambda function, an HTTP endpoint, a private service through a VPC link, or a direct call to another AWS service.
AuthorizerA check that runs before your code: IAM signatures, Amazon Cognito or JSON Web Tokens, or a Lambda function you write.
ThrottlingLimits on requests per second, applied per account and Region and optionally per stage, route or API key, so one caller cannot flood the rest.
StageA named, deployed version of an API, such as dev or prod, with its own settings, logs and limits.

Choosing

When to use it, and when not

Use it when

  • You need to push small changes from the fast lane to many browser screens within a second or two and want no servers to run.
  • Your push logic already lives in Lambda functions, for example a function reading DynamoDB Streams, and you are comfortable keeping the list of connections yourself.
  • You need a small, governed read API for an operational system, such as current limits per press, with sign-in, throttling and audit logs.
  • You want AWS WAF, private endpoints or usage plans in front of an internal API, which REST APIs give you directly.
  • Request and response stay short, well under the integration timeout, and the payloads are small.

Avoid it when

  • You want people to ask analytical questions; give them Databricks SQL, AI/BI dashboards or Genie instead of hand-built endpoints over the lake.
  • You need publish and subscribe with channels and fan-out handled for you; AppSync Events does that without a connection table.
  • The browser can tolerate a refresh every 30 seconds or more; plain polling of an HTTP API or a dashboard refresh is simpler and cheaper.
  • You need to stream large result sets or long-running jobs through the gateway; use files on S3 with presigned links or an asynchronous job instead.
  • Every message must reach every client exactly once; WebSocket push is best effort, so screens must reload a snapshot after they reconnect.

Production grade

What goes wrong in production

ProblemWhat breaksWhat to do
Stale connectionsBrowsers close tabs and lose Wi-Fi; posting to a dead connection ID returns an error (410 Gone) and wastes calls.Delete the connection ID from your table on $disconnect and on any 410 response; give the connection table a TTL so leftovers expire.
Two-hour and ten-minute cut-offsA WebSocket connection lasts at most two hours and closes after ten minutes with no traffic, so wall screens go quiet.Reconnect automatically in the client, send a small heartbeat every few minutes, and reload the snapshot from DynamoDB after each reconnect.
Fan-out is your codeAPI Gateway posts to one connection per call; a change watched by 400 screens needs 400 calls, and a slow loop delays the board.Group connections by press or line, post in parallel with bounded concurrency, and coalesce to at most one update a second per widget.
Frame and message sizeFrames above 32 KB must be split and messages above 128 KB are refused; a large snapshot pushed over the socket closes the connection with code 1009.Push only small change messages; let the client fetch the snapshot over an HTTP call to a prepared item instead.
Throttling at the account levelAll REST, HTTP and WebSocket APIs in one account and Region share one request-per-second quota, so a busy public API can starve the push path.Separate accounts for unrelated APIs, set stage and route limits, and request a quota increase before go-live; note that some newer Regions start lower.
Integration timeoutIntegrations time out at 29 seconds by default; a Lambda that runs a heavy query behind an API returns 504 errors under load.Keep handlers short and read prepared data; for long work return a job ID and let the client poll. Regional and private REST APIs can ask for a longer timeout, at the cost of throughput.
Reconnect stormsAfter a network blip at a plant, hundreds of screens reconnect at once and hit the new-connections-per-second quota.Use exponential backoff with random jitter in the client and watch the connect count on the $connect route.

Alternatives

What to compare it with

AlternativePick the alternative whenPick API Gateway when
AWS AppSync EventsYou want managed channels and fan-out, wildcard subscriptions and no connection table; the site keeps it as the simpler alternative to test.You want full control of routing in your own Lambda code, or already run API Gateway with its authorizers and logging.
Databricks Apps with server-sent eventsYou chose the Databricks-only lane and the app polls Lakebase every second, then pushes to the browser.You want true push from a change stream with no always-on app compute.
Azure Web PubSub or SignalRThe platform runs on Azure; these are managed push hubs with groups built in.You are on AWS; there is no reason to cross clouds for push.
Google Cloud Run with WebSocketsThe platform runs on Google Cloud, which has no managed WebSocket gateway; Cloud Run holds the connections.You want a fully managed connection service rather than a container you size.
Self-run Socket.IO, NGINX or KongYou need features the managed services lack, or already run a gateway cluster on Kubernetes.You do not want to patch, scale and monitor servers for a few hundred screens.

Cost

How you pay

You pay per use with no minimum. REST and HTTP APIs are billed per million requests, with HTTP APIs much cheaper per request than REST, plus optional REST cache hours. WebSocket APIs are billed per million messages, counted in 32 KB steps, plus connection minutes for the time each connection stays open. Data transfer out is billed at the usual rates. Check the API Gateway pricing page for your region, as list prices differ by region and tier.

What drives the bill

  • Number of messages pushed: changes per second times screens watching times widgets per screen.
  • Connection minutes: wall screens that stay connected all day for every shift.
  • Request volume on REST or HTTP APIs, and whether REST features such as caching are switched on.
  • The Lambda invocations and DynamoDB reads behind each connect, push and request, which often cost more than the gateway itself.

Cost traps

  • Pushing every raw reading instead of changes; the site's design caps each widget at one update a second for this reason.
  • Leaving the REST API cache on in every stage; it bills by the hour whether or not anyone calls.
  • Choosing REST APIs when HTTP APIs would do, and paying several times more per request for features you do not use.

Prices change; check the AWS pricing page for your region before deciding.

Security and governance

Keeping it safe

  • Sign-in: use IAM authorization for machine callers, Amazon Cognito or a JSON Web Token authorizer for people, and a Lambda authorizer on $connect for WebSocket screens; never leave $connect open.
  • Authorisation for data: the authorizer only says who connected; your push function must check which plants and presses each connection may see before sending.
  • Network: put REST APIs behind private endpoints reached through an interface VPC endpoint when only internal systems call them; attach AWS WAF to public REST APIs and WebSocket stages.
  • Encryption: all endpoints are HTTPS or WSS (encrypted WebSocket); use a custom domain with a certificate from AWS Certificate Manager and a minimum TLS policy.
  • Audit: CloudTrail records changes to APIs and stages; access logs in CloudWatch record each call, so keep personal data such as operator names out of paths and query strings.
  • Least privilege for the push function: allow execute-api:ManageConnections only on the one API and stage it serves.

Operating it

What to watch, and the limits

WatchWhy
ConnectCountWebSocket connection attempts on $connect; a spike means a reconnect storm after a network blip.
MessageCountMessages sent and received on the WebSocket API; tracks push volume and cost.
IntegrationError and ExecutionErrorFailures in the Lambda or service behind a WebSocket route; any steady rate means screens miss updates.
ClientErrorRequests rejected before your code, including throttling and failed sign-in.
5XXError and 4XXErrorServer and client errors on REST and HTTP APIs; 504s point to integration timeouts.
Push age at the screenYour own end-to-end signal: time from the reading on Kinesis to the update on screen, against the five-second target.
LimitValue and notes
Account throttle10,000 requests a second per account and Region across REST, HTTP and WebSocket APIs, burst 5,000; lower in some newer Regions; can be raised
New WebSocket connections500 a second per account and Region by default; can be raised
WebSocket connection life2 hours maximum, closed after 10 minutes idle; neither can be changed
WebSocket message and frame128 KB message, 32 KB frame; fixed
Integration timeout50 ms to 29 seconds; Regional and private REST APIs can ask for more

Limits and quotas checked 2026-11-11; many can be raised through Service Quotas.

Decisions

Situations and verdicts

SituationChoiceVerdict
Live board for 200 press screens across three plantsAPI Gateway WebSocket fed by DynamoDB Streams and Lambda, snapshot then changesPursue: true push within one to three seconds, serverless, and cheap when only changes are sent.
Same board, team wants no connection table to maintainAppSync Events with a channel per linePursue with care: simpler fan-out, but test latency, sign-in and cost in the physical step before switching.
Finance wants a daily sales API for the ERP teamExpose a Databricks SQL warehouse or a Delta Share instead of a Lambda behind API GatewayDrop: the gateway adds code and timeouts for a job the lakehouse serves directly.
Plant system needs current recipe limits per pressHTTP API with IAM sign-in reading a small prepared item in DynamoDBPursue with care: fine while it stays small and read-only; watch the shared account throttle.
Existing REST APIs for store and order lookupsLeave them in place and keep them separate from the push pathKeep if you have it: they work; move them to their own account if they compete for the throttle.

FAQ

Questions people ask

How long can an API Gateway WebSocket connection stay open?

Two hours at most, and it closes after ten minutes with no messages. Neither limit can be changed. Clients should send a heartbeat and reconnect automatically, then reload their snapshot.

What is the difference between REST APIs and HTTP APIs in API Gateway?

REST APIs have more features: request validation, API keys and usage plans, caching, private endpoints and direct WAF support. HTTP APIs are lighter and cheaper per request, with built-in JSON Web Token sign-in. Pick HTTP unless you need a REST-only feature.

Can API Gateway broadcast one message to all connected clients?

Not by itself. You post to each connection ID separately through the @connections endpoint, so your code keeps the list and loops over it. AppSync Events handles broadcast to channels for you.

Can I raise the 29-second integration timeout?

For Regional and private REST APIs, yes, through a quota request, and AWS may lower your throttle quota in exchange. WebSocket and edge-optimized APIs stay at 29 seconds. Long jobs should run asynchronously instead.

Should dashboards query the lakehouse through API Gateway?

No. Use Databricks SQL warehouses, AI/BI dashboards or a BI tool's connector. API Gateway in this platform is for pushing live changes and for a few small operational APIs.

Sources

Checked against

Checked 2026-11-11.

Related

Where it connects

Streaming on AWS and Databricks · Real-time mode and the 1-second lane · Real-time analytics · AWS AppSync · Amazon DynamoDB Streams · AWS Lambda · All AWS data services

← Lambda · AppSync →