REST, GraphQL, gRPC and WebSocket: how to choose

REST

REST (Representational State Transfer) is an architectural style built directly on HTTP. Data is organized as resources, each with its own address, and the HTTP methods decide what happens to them:

GET    /wp-json/wc/v3/products        get products
GET    /wp-json/wc/v3/products/42     get one product
POST   /wp-json/wc/v3/orders          create an order
PUT    /wp-json/wc/v3/products/42     update a product
DELETE /wp-json/wc/v3/products/42     delete a product

The example is WooCommerce’s own REST API, which is built in. REST is stateless: every request contains everything the server needs, including authentication, and responses are usually JSON that can be cached with ordinary HTTP headers. It’s simple, supported everywhere and easy to test with tools every developer knows, which is why almost every public API is built this way.

The rest of HTTP is used too. The status code says how it went: 200 is a response, 201 means something was created, 401 and 403 are about access, 404 about something that doesn’t exist, and 429 means the client is asking too often. Lists come in pages, so a client fetches, say, 100 products at a time and follows the next page instead of getting the whole catalog in one response. And the version is in the address (v3), so the API can change without breaking existing integrations.

Authentication uses a key sent with every request. WooCommerce uses a key pair you create under WooCommerce → Settings → Advanced → REST API, and WordPress itself has application passwords under your user profile. Both must be sent over HTTPS, and each integration should have its own keys, so you can shut one off without touching the others.

The weakness is that the API decides which fields you get. If an app needs to show a product with reviews and stock status, that can take three calls, each returning far more than is needed. That’s exactly the problem GraphQL was created to solve.

GraphQL

GraphQL was developed by Facebook and turns the model around: there’s a single endpoint, and the client describes exactly the data it wants.

query {
  product(id: 42) {
    name
    price
    reviews(first: 3) { rating author }
  }
}

The response has exactly the shape the query described, and data from several related objects is fetched in one call. The API is described in a typed schema, so tools can validate queries and generate documentation. That makes GraphQL strong for apps and separate front ends with many different screens.

Reads are called queries, and changes are called mutations: adding an item to the cart or creating an order is a mutation that also chooses which fields it wants back. WordPress doesn’t have GraphQL built in, but the WPGraphQL extension adds it, and there’s a matching extension for WooCommerce. That’s the usual route when an online store gets a separate front end built in, for example, React.

The price is a more complex server. Because queries typically go to the same address with POST, ordinary HTTP caching doesn’t work on its own, so you use fixed, stored queries or server-side caching instead. And because the client decides how deep it asks, the server has to limit how heavy a query may be, so one client can’t bring it down.

gRPC

gRPC is Google’s answer to communication between services where speed and strict contracts matter most. The client calls functions on the server, and the messages are defined in the compact binary format Protocol Buffers. The contract is written in a .proto file:

service Inventory {
  rpc GetStock (ItemRequest) returns (Stock);
}

message ItemRequest { string sku = 1; }
message Stock       { string sku = 1; int32 quantity = 2; }

Client and server code is generated from the file in many languages, so both sides always agree on what a message contains. It runs over HTTP/2 with streaming in both directions, which is why it’s common inside larger systems, where many small services call each other thousands of times a second.

On the other hand, a browser can’t call gRPC directly. That takes the gRPC-Web variant and a proxy that translates between them. Binary messages are also harder to debug than JSON, so gRPC is rarely the right choice for a public integration or for an online store that has to talk to external systems.

WebSocket

The other three always start with the client asking. WebSocket is different: after an initial HTTP handshake, the connection stays open, and both server and client can send messages whenever they want. The handshake is an ordinary HTTP request asking to switch protocols:

GET /live HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade

If the server says yes, it’s no longer HTTP but a two-way connection running over the same TCP connection, encrypted as wss:// the same way as HTTPS. That gives very low latency and is especially well suited to chat, live notifications and dashboards that update continuously.

On the other hand, every open connection uses resources on the server, connections have to be re-established when they drop, and ordinary PHP hosting isn’t built for it, because PHP ends each request as soon as the response is sent. If a WordPress site needs real time, the WebSocket part usually runs as a separate service alongside it or with a provider built for it. If the server only needs to send updates to the browser and not the other way, Server-Sent Events are often a simpler alternative.

Webhooks: when the system tells you itself

Webhooks aren’t an API style on a par with the four, but they belong here, because they solve the problem most online stores actually have: getting notified when something happens. Instead of your inventory system asking WooCommerce every minute whether new orders have come in, WooCommerce sends an HTTP request to the inventory system the moment the order is created.

In WooCommerce, you create them under WooCommerce → Settings → Advanced → Webhooks and choose which event triggers them, such as a new order or an updated product, and which address receives them. Every message is signed with a secret key in the X-WC-Webhook-Signature header, so the receiver can check that it really comes from your store. The receiver should respond quickly and be able to handle the same message arriving more than once. If delivery fails, WooCommerce counts it, and after five failures in a row it disables the webhook, so someone has to keep an eye on it. Many integrations combine the two: webhooks to get notified, and REST to fetch or change the data the message is about.

Comparison

The differences in brief, side by side:

	REST	GraphQL	gRPC	WebSocket
Model	Resources and HTTP methods	Queries against a schema	Function calls	Open two-way connection
Format	Usually JSON	JSON	Protocol Buffers (binary)	Any
Transport	HTTP	HTTP	HTTP/2	WebSocket over TCP
Contract	Documentation, optionally OpenAPI	Typed schema	.proto file, code is generated	None fixed
Streaming	No	Only with add-ons	Yes, both ways	Yes, both ways
Caching	Easy with HTTP	Harder	Harder	Not relevant
Browser	Yes	Yes	Only through a proxy	Yes
Best for	Public APIs and integrations	Apps and front ends with varying needs	Communication between your own services	Real time

How to choose

Four questions settle it in most cases:

1. Will anyone other than you use the API? Then REST. Anyone can call it, and it’s what developers expect.
2. Do the clients need very different data? An app, a store front end and a point-of-sale system that each want their own slice point to GraphQL.
3. Is it only your own services talking to each other, and does every millisecond count? Then gRPC is worth a look.
4. Does data have to arrive the moment it changes, and often? WebSocket for both directions, Server-Sent Events or webhooks if it only goes one way.

If you answer no to the last three, REST is almost always right. It’s the simplest to build, run and debug, and it’s what the systems an online store has to talk to support.

What does it mean for an online store?

Most integrations for a WooCommerce store are built with REST, because WooCommerce, payment providers, shipping companies and most ERP and accounting systems offer REST APIs. Combine it with webhooks, where one system sends a message to another by itself when something happens, for example when an order is created or a stock level changes. Then you don’t have to keep asking.

GraphQL makes sense if you build a separate front end or app on top of WordPress, where extensions exist that add a GraphQL API. gRPC and WebSocket are rare in ordinary online stores, but can be relevant in larger solutions with their own services or live features.

Whatever the style, the same applies: use HTTPS, give each integration its own keys with only the permissions it needs, handle errors and retries so an order is never created twice, and log what happens so errors can be found.

Frequently asked questions

Is GraphQL better than REST?

No, it’s different. GraphQL is strong when many different clients need different data. REST is simpler, easier to cache and better supported by the systems an online store typically has to talk to.

Does WordPress have an API?

Yes. WordPress has a built-in REST API under /wp-json/, and WooCommerce adds its own for products, orders and customers. Both require authentication for anything that isn’t public.

Can WooCommerce use GraphQL?

Not by default. With WPGraphQL and a matching WooCommerce extension, products, the cart and orders can be read and changed with GraphQL. It’s mostly relevant if the store gets a separate front end.

When should I use WebSocket?

When data has to arrive immediately and often, such as in a chat or a live dashboard. For things that only update now and then, ordinary requests or webhooks are simpler.

Do your systems need to talk to each other?

We build integrations between WooCommerce and inventory, ERP, accounting and shipping, and choose the solution that fits the job. See more about custom development.