REST API vs WebSocket API: The Real Difference, and Which to Use (Plus AWS API Gateway)

REST API vs WebSocket API, in one sentence each: a REST API works like sending letters, where the client asks a question, the server answers, and the conversation is over, while a WebSocket API works like a phone call, where one connection stays open and either side can speak at any moment. Use REST for ordinary actions (load a page of products, save an order, look up a customer), and use WebSocket when the server needs to push news to the user as it happens: chat messages, live dashboards, game moves, delivery tracking. Here is the part most comparisons leave out: WebSocket does not replace REST; real-time apps almost always use both, REST for actions and history, WebSocket for live updates. And the wrong choice can be expensive: on AWS API Gateway, a live status screen that "refreshes" by asking a REST API every two seconds for 1,000 users costs about $1,109 a month, while the same screen over a WebSocket API costs about $11. Below, we start from the basics, compare them properly, cover webhooks and Server-Sent Events, and then show how REST, HTTP and WebSocket APIs differ on AWS.

Jake's phone repair shop wanted a live repair board: a screen at the counter, and a page on customers' phones, showing each repair moving from "received" to "diagnosing" to "ready for pickup." A freelancer built it in a weekend. The page asked the server "anything new?" every two seconds. It worked, until the month the shop got busy. The AWS bill for the API grew to several hundred dollars, customers complained that the page drained their phone batteries, and technicians noticed the board lagged when the shop's Wi-Fi was busy. Jake asked Ethan whether he needed "a bigger server." Ethan said he needed a different kind of conversation.

The basics: what an API, REST and WebSocket actually are

Before comparing them, it helps to pin down four words, because the names get used loosely.

• An API (application programming interface) is a set of rules one program uses to talk to another. When a phone app shows your bank balance, it asked the bank's API.
• HTTP is the language of the web. Your browser sends a request ("GET this page"), the server sends a response (the page, plus a status code such as 200 OK or 404 Not Found), and that exchange is finished.
• REST is a style of designing APIs on top of HTTP. Everything is a resource with an address, such as /repairs/1042, and you act on it with HTTP's verbs: GET to read, POST to create, PUT or PATCH to change, DELETE to remove. Each request carries everything the server needs, so the server does not have to remember the client between requests; that is what "stateless" means.
• WebSocket is a different protocol. A connection starts as an ordinary HTTP request with a special "upgrade" header, the server agrees, and from then on the same connection stays open. Both sides can send messages whenever they like, in either direction, until one side closes it. The addresses start with ws://, or wss:// when encrypted, which is what you should always use.

So, is a WebSocket an API? Strictly, WebSocket is a protocol, like HTTP. A WebSocket API is an API built on that protocol: a defined set of messages that clients and server send each other over the open connection.

"So REST is like sending letters," Jake said, "and WebSocket is like a phone call."

"That's it," Ethan said. "Your freelancer built a repair board that sends a letter every two seconds asking 'anything new?' Most of the replies say 'no.' You're paying postage on thousands of empty envelopes. A phone call lets the shop say 'ready for pickup' the moment it's true."

REST in five minutes: resources, verbs and status codes

If you are learning APIs, three ideas carry you through almost any REST API you will ever call or build.

Resources are nouns with addresses. A good REST API names things, not actions: /repairs for the collection, /repairs/R-1042 for one repair, /repairs/R-1042/notes for its notes. The action comes from the verb, not the URL, so you will not see /getRepair or /deleteRepair in a well-designed REST API.

Verbs say what to do. GET reads and never changes anything. POST creates something new. PUT replaces a resource, and PATCH changes part of it. DELETE removes it. Because GET is safe and repeatable, browsers and caches can store GET responses, which is a large part of why REST scales so well.

Status codes say what happened. Every response carries a three-digit code, and reading it is the first step in any API troubleshooting:

Code	Meaning
200 / 201 / 204	Success; 201 means something was created, 204 means success with no body
400	The request itself is wrong (missing field, bad format)
401 / 403	Not signed in / signed in but not allowed
404	That resource does not exist
409	Conflict, such as two people editing the same thing
429	Too many requests; slow down and retry later
500 / 502 / 504	Something broke on the server side, or behind the gateway, or it took too long

Two of those codes come up constantly with API Gateway: 429 when throttling limits are hit, and 502 when a Lambda function returns its answer in the wrong shape. Our guides to the 502 response-shape error and to throttling cover both in detail. WebSockets have no per-message status codes at all, which is one reason REST stays easier to debug.

REST vs WebSocket: the real differences

	REST API	WebSocket API
Connection	New request each time; closes after the response	One connection stays open
Who can start a message	Only the client	Client or server, any time
Server remembers the client?	No; each request is self-contained	Yes, for as long as the connection lasts
Overhead per message	Full HTTP headers every time	A few bytes per message after connecting
Caching	Works naturally (browsers, CDNs)	Not applicable
Scaling	Easy; any server can answer any request	Harder; connections must be tracked
Errors	Clear status codes per request	You design your own error messages; connections can drop
Tooling	Everywhere: browsers, curl, Postman, every language	Good, but less universal; some proxies interfere
Best at	Reading and changing data on request	Live, two-way, frequent updates

The single most important line is the second one. In REST, the server can never speak first. If the client wants to know about a change, it has to ask, and keep asking. That asking-in-a-loop is called polling, and it is behind most "our real-time feature is slow and expensive" stories, including Jake's.

When a REST API is the right choice

REST is the default for good reasons, and most APIs should be REST APIs:

• Create, read, update, delete. Loading a product list, saving a booking, updating an address, deleting a draft. Each is a single question with a single answer.
• Public APIs for other developers. Everyone knows how to call a REST API, and it is easy to document and test.
• Data that benefits from caching. A list of phone models or repair prices can be cached by browsers and content delivery networks, so most requests never reach your server.
• Mobile apps on unreliable networks. Each request stands alone, so a dropped signal costs one retry, not a broken session.
• Anything where "a few seconds old" is fine. If the user can refresh, or the data changes rarely, REST is simpler to build and to run.

For Jake's shop, the booking form, the price list, customer lookups and the repair history all stayed REST. That is most of the system.

When a WebSocket API is the right choice

WebSocket earns its extra complexity when the server needs to tell clients about things as they happen, often and quickly:

• Chat and messaging, where a message from one person must appear for another immediately.
• Live dashboards and status boards, like Jake's repair board, stock tickers, or delivery tracking.
• Collaborative tools, where several people edit the same document or board.
• Multiplayer games, where every move goes to every player.
• Notifications inside an open app, such as "your order shipped."
• Two-way device communication, where a device both reports readings and receives commands.

The test is simple: does the server need to speak first, more than occasionally? If yes, a WebSocket (or one of the alternatives below) belongs in the design. If the client only needs fresh data when the user does something, REST is enough.

Most real-time apps use both

The mistake that follows "WebSocket is faster" is moving everything onto the WebSocket. It makes the system harder to build, test, cache and secure, for no gain. The pattern almost every real-time app settles on looks like this:

• REST for actions and history. Log in, load the last 50 messages, create an order, change a setting.
• WebSocket for live news. "A new message arrived," "repair 1042 is ready," "the price changed." Often the live message just says what changed, and the app fetches the details over REST.

Jake's board ended up exactly that way. The page loads the current list of repairs with one REST call, then opens a WebSocket. When a technician marks a repair ready, the back end sends a short message such as {"repair":"R-1042","status":"ready"} to every open board, and the screens update instantly. If a phone loses its connection, the page reconnects and makes one REST call to catch up on anything it missed.

Which one for my project? Ten quick examples

• An online store: REST. Product pages, cart and checkout are classic ask-and-answer, and caching helps.
• A chat app: WebSocket for new messages, REST for history, sign-in and settings.
• An AI chatbot that types its answer word by word: Server-Sent Events over HTTP is the common choice, since the stream flows one way.
• A live sports score page: SSE or WebSocket; SSE if viewers only watch.
• A payment confirmation from your payment provider: a webhook to your server, then a WebSocket or a refresh to update the customer's screen.
• A notification bell in a web app: WebSocket or SSE for instant alerts, or polling once a minute if "within a minute" is good enough.
• A multiplayer game: WebSocket, since moves flow both ways constantly.
• An internal admin panel: REST; a refresh button is fine.
• Thousands of sensors or machines: MQTT through a service such as AWS IoT Core, which is built for devices.
• A live repair, delivery or order-status board: REST to load, WebSocket (or SSE) to update, exactly like Jake's.

Notice how often the answer is "REST, plus something." The real-time piece is usually a thin layer on top of a REST application, not a replacement for it.

The alternatives: polling, Server-Sent Events and webhooks

WebSocket is not the only way to get updates to users, and for some jobs it is not the best one. Here are the options, from simplest to most capable:

Technique	How it works	Good for
Short polling	Client asks every few seconds	Rare updates, few users, quick prototypes
Long polling	Client asks; server holds the request open until there is news	When WebSockets are blocked; older systems
Server-Sent Events (SSE)	One long HTTP response; server keeps sending events to the browser	One-way live feeds: notifications, progress, AI text streaming
WebSocket	Open two-way connection	Chat, games, collaboration, frequent two-way updates
Webhook	One server calls another server's URL when something happens	Server-to-server events: payments, form submissions, Git pushes

Server-Sent Events: the underrated option

If updates only flow from server to browser, SSE is often simpler than WebSocket. It runs over ordinary HTTP, so it passes through proxies and firewalls that sometimes block WebSockets, and browsers reconnect automatically if the connection drops. It is how many AI chat apps stream their answers word by word. Its limits: it is one-way (the browser still uses normal requests to send things), and it carries text, not binary data. A live repair board that only shows status could be built with SSE; Jake chose WebSocket because technicians' tablets also send updates through the same connection.

API vs webhook vs WebSocket

These three get confused because all involve "sending data." The difference is who calls whom, and for how long. With an API call, your program asks another system for something. With a webhook, the other system calls your URL when an event happens, for example a payment provider telling your shop "payment succeeded"; it is a one-off HTTP request between servers, and your server must be reachable on the internet to receive it. With a WebSocket, a connection stays open, usually to a browser or app, for ongoing two-way messages. A common real system uses all three: a webhook from the payment provider, a REST API for the app, and a WebSocket to update the screen.

Web API vs REST API, and web service vs REST API

Two more comparisons show up in searches next to this one, and both are naming questions:

• Web API vs REST API. "Web API" means any API you reach over the web. REST is one style of web API. So every REST API is a web API, but not every web API is RESTful; GraphQL APIs, SOAP services and WebSocket APIs are web APIs too.
• Web service vs REST API. "Web service" is an older, broader term, often used for SOAP services, which exchange XML messages with strict contracts. REST APIs are lighter, usually exchange JSON, and are what most new web APIs use.

GraphQL and gRPC: where they fit

Two more names come up in API discussions. GraphQL is a query language for APIs: instead of many REST endpoints, the client sends one query describing exactly which fields it wants, and gets exactly that back. It usually runs over ordinary HTTP, and its real-time feature, subscriptions, typically runs over a WebSocket, so GraphQL apps face the same push-or-poll choice described here. gRPC is a fast, binary way for services to call each other, built on HTTP/2, with built-in streaming in both directions. It shines between back-end services; browsers need a translation layer to use it, so it rarely replaces REST or WebSocket for web pages. If you are starting out, learn REST first, then WebSocket; GraphQL and gRPC make far more sense once those two are familiar.

Designing WebSocket messages that stay manageable

Because WebSockets have no built-in structure like REST's URLs and status codes, you have to design one. A few habits keep a real-time feature maintainable as it grows:

• Use a small envelope on every message: an action or type field saying what the message is, and a data field with the content. On API Gateway, the action field doubles as the route selector.
• Include an ID and a time on each update, so a client that receives the same message twice, or out of order, can tell, and ignore the older one.
• Send changes, not whole screens. "Repair R-1042 is ready" is a few bytes; the whole board is kilobytes, and must be split once it passes 32 KB.
• Add a version number to the message format, so old app versions on customers' phones do not break when you add fields.
• Reply to important client messages with a short acknowledgment, since nothing like an HTTP 200 tells the client its update arrived.

On AWS: API Gateway's REST, HTTP and WebSocket APIs

Amazon API Gateway, AWS's service for putting an API in front of your code, offers three API types, and the names add a twist: on AWS, both "REST API" and "HTTP API" are REST-style APIs. The difference between those two is features and price, not style.

	REST API	HTTP API	WebSocket API
Style	Request/response	Request/response	Persistent, two-way
Price (US East, first tier)	$3.50 per million requests	$1.00 per million requests	$1.00 per million messages + $0.25 per million connection minutes
Strengths	API keys and usage plans, request validation, caching, AWS WAF, private APIs	Cheaper, simpler, built-in JWT authorizers	Server push to connected clients
Integration timeout	29 s; can be raised for Regional and private APIs	30 s	29 s, fixed
Size limits	10 MB payload	10 MB payload	128 KB message, 32 KB frames

Rule of thumb on AWS: start with an HTTP API for a normal REST-style back end; it costs less than a third as much per request. Choose a REST API when you need its extra features, such as usage plans with API keys for customers, request validation, response caching, a private API inside a VPC, or AWS WAF attached directly. Choose a WebSocket API for the live, two-way part. Our API Gateway guide explains the service from the beginning.

HTTP API vs REST API on AWS: a quick checklist

Because both are REST-style, the choice comes down to whether you need any of the features only the REST API type has. Choose a REST API if you need even one of these: API keys with usage plans to meter and throttle individual customers, request validation before your code runs, request and response transformation with mapping templates, response caching, a private API reachable only inside your VPC, edge-optimized endpoints, resource policies, or AWS WAF attached directly. Otherwise choose an HTTP API: it is cheaper ($1.00 instead of $3.50 per million requests), has lower latency, supports JWT authorizers out of the box, and has simpler CORS settings and automatic deployments. You can run both side by side, and many teams do: an HTTP API for the app's main back end, and a REST API only for the partner-facing endpoints that need usage plans.

How a WebSocket API works on API Gateway

API Gateway handles the hard part, keeping thousands of connections open, so your back end, usually Lambda functions, never has to. It works through routes:

• $connect runs when a client connects. This is where you check who they are and record the connection.
• $disconnect runs when a connection closes, so you can clean up.
• $default catches any message that matches no other route.
• Custom routes such as updateStatus are picked by a field in each message. With the common route selection expression $request.body.action, a message like {"action":"updateStatus","repair":"R-1042"} goes to the updateStatus route.

Every connection gets a connection ID. To push a message to a client, your code sends it to that ID through the API's connection management endpoint, the @connections URL of your stage. Because Lambda functions do not remember anything between runs, apps store connection IDs somewhere shared, most often a DynamoDB table: add the ID on $connect, remove it on $disconnect, and look up who to notify when something changes. If your clients cannot connect at all, the usual cause is a missing route or integration; our WebSocket connection guide covers that error.

Plan around four limits from the start:

1. Connections last at most 2 hours. Clients must reconnect, so build reconnect logic from day one.
2. Idle connections close after 10 minutes. If nothing is sent for 10 minutes, API Gateway closes the connection; a small "ping" message every few minutes keeps it alive.
3. Messages are limited to 128 KB, in 32 KB frames. Larger messages must be split; send big data by REST and use the WebSocket only to say it is ready.
4. New connections are limited to 500 per second per account and Region by default (it can be raised). There is no cap on total open connections; the connection rate and the 2-hour lifetime decide it.

Build a WebSocket API on AWS, step by step

Here is the shortest working path in the API Gateway console, with Lambda as the back end:

1. Open API Gateway, choose Create API, and pick WebSocket API.
2. Set the route selection expression to $request.body.action.
3. Add the predefined routes $connect, $disconnect and $default, plus a custom route such as updateStatus.
4. Attach a Lambda integration to each route. One function per route keeps things clear; small apps often use one function that checks the route name.
5. Create a stage, such as production, and deploy. API Gateway shows two URLs: the wss:// address clients connect to, and the https:// connection management URL your back end uses to push messages.
6. Give the Lambda function's role permission to call execute-api:ManageConnections on the API, and to read and write the DynamoDB table of connection IDs.
7. Test from a terminal with npx wscat -c wss://a1b2c3d4e5.execute-api.us-east-1.amazonaws.com/production, then type a message such as {"action":"updateStatus","repair":"R-1042"}.

Pushing a message from Lambda takes a few lines with the AWS SDK for Python. The endpoint is the stage's connection management URL:

import json, boto3

api = boto3.client(
    "apigatewaymanagementapi",
    endpoint_url="https://a1b2c3d4e5.execute-api.us-east-1.amazonaws.com/production",
)

def notify(connection_id, repair_id, status):
    try:
        api.post_to_connection(
            ConnectionId=connection_id,
            Data=json.dumps({"repair": repair_id, "status": status}).encode(),
        )
    except api.exceptions.GoneException:
        # the client has disconnected; remove its ID from the table
        pass

That GoneException branch matters. Connections disappear without warning when phones change networks, so cleaning up stale IDs as you find them keeps the table accurate and the push loop fast.

The browser side: connect, listen, reconnect

In a web page, the built-in WebSocket object does the work. The essentials are listening for messages and reconnecting when the connection drops:

let socket, retry = 0;

function connect() {
  socket = new WebSocket("wss://a1b2c3d4e5.execute-api.us-east-1.amazonaws.com/production");
  socket.onopen = () => { retry = 0; refreshBoardFromRest(); };
  socket.onmessage = (event) => updateRepair(JSON.parse(event.data));
  socket.onclose = () => setTimeout(connect, Math.min(30000, 1000 * 2 ** retry++));
}

setInterval(() => {
  if (socket && socket.readyState === WebSocket.OPEN) {
    socket.send(JSON.stringify({ action: "ping" }));
  }
}, 5 * 60 * 1000);   // under API Gateway's 10-minute idle limit

connect();

Three habits are built into those few lines: the page reloads the full board over REST each time it connects, so nothing missed while offline is lost; reconnect delays grow (1, 2, 4 seconds and so on, up to 30) so a server problem is not met with a flood of retries; and a ping every five minutes keeps idle connections open. A ping action needs a route or the $default route on the server, even if it does nothing.

Testing both from a terminal

Checking an API from the command line is the fastest way to tell whether a problem is in the API or in your app. For REST, curl -i https://api.example.com/repairs/R-1042 shows the status code, headers and body in one go. For WebSocket, npx wscat -c wss://a1b2c3d4e5.execute-api.us-east-1.amazonaws.com/production opens a connection you can type into, and shows every message the server pushes back. If wscat connects and receives messages but your page does not, the problem is in the page; if wscat cannot connect either, look at the API's routes, its authorizer, and its logs.

The cost math: why polling gets expensive

Here is Jake's board, priced on API Gateway in US East at list prices. Assume 1,000 people have the board open for 8 hours a day, 22 days a month, and each repair produces, on average, enough updates that each viewer receives about 50 messages an hour.

Approach	Usage per month	Cost
REST API, polling every 2 s	1,000 × 14,400 polls a day × 22 = 316.8 million requests × $3.50/M	About $1,109
HTTP API, polling every 2 s	Same 316.8 million requests at $1.00/M (and $0.90/M above 300 million)	About $315
WebSocket API	10.56 million connection minutes × $0.25/M + 8.8 million messages × $1.00/M	About $11

The back-end compute follows the same shape: every poll wakes your Lambda function or database to answer "nothing new," while the WebSocket version only does work when something actually changes. Two cautions keep the comparison honest. WebSocket messages are metered in 32 KB pieces, so a 40 KB message counts as two. And at very low traffic, a handful of users checking occasionally, polling a cheap HTTP API costs pennies too. The gap opens with frequent polling and many users, which is exactly what a "live" screen means.

Moving from polling to WebSocket without breaking anything

If you already have a polling app, as Jake did, you do not need a big rewrite. The switch can be gradual and safe:

1. Keep every REST endpoint. The WebSocket adds notifications; it does not replace reading and writing data.
2. Add the WebSocket for "something changed" messages only, with the smallest possible payload: which item, and its new state.
3. Ship the new client behind a switch, so a few users try it first.
4. Keep slow polling as a safety net, for example once a minute instead of every two seconds, for clients whose WebSocket cannot connect.
5. Watch the numbers: API requests, connection counts, connection errors, and how quickly updates appear.
6. Turn the old fast polling off once the new path has proven itself for a couple of weeks.

Jake's freelancer made the change in two evenings with exactly this plan. The slow safety-net poll still catches the occasional customer on a strict hotel Wi-Fi that blocks WebSockets.

Other real-time options on AWS: AppSync Events and IoT Core

API Gateway's WebSocket API is not the only managed way to push updates on AWS, and for some apps another service is less work:

• AWS AppSync Events is a managed publish-and-subscribe service over WebSockets. Clients subscribe to named channels (such as /repairs/shop1), and anything published to a channel reaches every subscriber, without you storing connection IDs or writing a fan-out loop. For broadcast-style updates, such as Jake's board, it removes the most tedious code.
• AWS AppSync GraphQL subscriptions push changes to apps that already use GraphQL for their data.
• AWS IoT Core is built for devices: millions of sensors and machines talking over MQTT, which browsers can also reach over WebSockets.

A practical way to choose: API Gateway WebSocket APIs when you want full control of every message and route; AppSync Events when you mainly broadcast updates to groups of users; IoT Core when the "clients" are devices.

Security for REST and WebSocket APIs

• Always encrypt. Use HTTPS for REST and wss:// for WebSockets. API Gateway endpoints use TLS by default.
• Authenticate REST requests every time. On API Gateway that means IAM, Amazon Cognito user pools, JWT authorizers on HTTP APIs, or Lambda authorizers. API keys in usage plans are for metering and throttling customers, not for proving who someone is.
• Authenticate WebSockets at $connect. On API Gateway, the authorizer runs when the connection opens, not on each message, so a long-lived connection keeps the identity it started with. Keep sessions short, and check permissions in your back end before acting on sensitive messages.
• Check where browser connections come from. Browsers do not apply the same cross-origin rules to WebSockets as to ordinary requests, so check the Origin header or require a token at connect time.
• Limit rates. Throttling on API Gateway protects your back end and your bill from runaway clients; our 429 throttling guide explains the account and stage limits.

REST vs WebSocket performance

For a single request, the difference is small. Where WebSocket pulls ahead is many small, frequent messages: there is no new connection or full set of HTTP headers per message, so each update arrives with less delay and fewer bytes. Where REST pulls ahead is anything cacheable, since a response served from a browser or content-delivery cache never reaches your server at all, and anything that must scale across many servers without coordination. Modern HTTP/2 and HTTP/3 also make repeated REST requests cheaper than they used to be, which narrows the gap for moderate polling. The honest summary: choose by communication pattern (who needs to speak first, and how often), not by raw speed claims.

Common mistakes with WebSockets

• No reconnect logic. Connections drop: phones change networks, laptops sleep, and API Gateway closes connections after 2 hours. Clients must reconnect automatically and then fetch anything they missed over REST.
• Keeping state in one server's memory. With more than one server, or with Lambda, a list of connected users in memory goes missing. Store connections in a shared database.
• Sending everything through the socket. Large files and history belong in REST calls or S3; the socket carries short notifications.
• No heartbeat. Without occasional messages, idle connections are closed silently by API Gateway, proxies or mobile networks.
• Corporate networks. Some company proxies and firewalls block or break WebSocket upgrades. Test from real customer networks, and keep SSE or long polling as a fallback for business users.

For IT admins: running real-time APIs in production

Real-time features change operations in a few ways worth planning for. Monitor connection counts, connection errors and message volumes, not only request counts, using API Gateway's CloudWatch metrics. If you protect APIs with AWS WAF, note that WAF attaches directly to API Gateway REST APIs; for other API types, put Amazon CloudFront in front or protect the back end separately. Check that company proxies and security tools allow WebSocket upgrades to your domains. Set budgets that separate connection minutes from messages, so a client bug that reconnects in a loop shows up quickly. And document the fallback: when real-time fails, users should still see correct data after a refresh, because the source of truth stays in your REST API and database.

REST API vs WebSocket API: frequently asked questions

Jake's repair board still looks the same to customers, except that "ready for pickup" now appears the moment a technician taps it, phones no longer run warm, and the API line on the bill is smaller than the shop's coffee budget. The REST API never went away; it still does nearly all the work. It just stopped being asked the same empty question thousands of times an hour. If you have been unsure which one your project needs, you are in good company: the answer is usually "mostly REST, plus a WebSocket for the moments that matter."

Revision note. Written October 5, 2026. If the difference between asking and listening has been fuzzy, you were never far off; may your next design send fewer empty envelopes.