The Types of APIs: REST, GraphQL, gRPC, SOAP & WebSockets

In the last course, an API was one idea: client asks, server answers. But there's more than one style of asking — and choosing the right one is one of the first real decisions a builder makes. This course walks through the five you'll meet, in plain language: what each is, when it shines, and the standard that defines it.

REST is the style you met in the last course without knowing its name. Addresses (/users/42), verbs (GET, POST, PUT, DELETE), JSON in and out, status codes. That is REST. It's the most common API style on earth because it's simple, it rides on the plain mechanics of the web, and anyone can read it.

REST treats everything as a resource — a thing with an address — and you act on it with the standard verbs. A list of users is /users. One user is /users/42. To update them, you PUT /users/42. It's intuitive because it mirrors how the web already works.

Use REST when: you're building a normal web or mobile API, you want simplicity and broad compatibility, and most requests map cleanly to "read/create/update/delete a thing." Which is most of the time — start here unless you have a reason not to.

REST has one mild frustration: each endpoint returns a fixed shape. Want a user's name and just their last three orders? You might have to call /users/42, then /users/42/orders, then trim what you don't need — several round trips, often with too much or too little data.

GraphQL flips this. There's usually a single endpoint, and the client writes a query describing exactly the data it wants — and gets back precisely that shape, no more, no less, in one request.

query {
  user(id: 42) {
    name
    orders(last: 3) { total }
  }
}

The server returns just the name and those three order totals. Nothing wasted, one trip.

Use GraphQL when: clients need flexible, varied slices of data (think a rich mobile app with many screens), you want to avoid over-fetching, and a single, evolving data graph suits your domain. The trade-off: more setup and complexity than REST, so it earns its keep on bigger, data-hungry front-ends.

REST and GraphQL are friendly for browsers and humans. But inside a large system, your own services need to talk to each other constantly — and there, human-readability matters less than raw speed.

gRPC is built for that. Instead of human-readable JSON, it sends compact binary messages that are much smaller and faster to process, and it uses a strict, shared definition of every message so both sides always agree on the format. It's the quiet workhorse connecting services inside big systems.

Use gRPC when: services inside your own system talk to each other at high volume and you want speed and strict contracts. Don't reach for it as a public, browser-facing API — it's not made for that. Think internal plumbing, not front door.

SOAP predates REST and is far more rigid. Messages are wrapped in verbose XML (an older, tag-heavy data format), with formal rules, strict contracts, and built-in standards for security and reliability. That strictness made it the choice for big, high-stakes enterprise systems — and it's why you'll still meet it in banking, insurance, payments, and government.

You probably won't build a new SOAP API today. But because it runs so much critical infrastructure, builders regularly have to connect to one. Knowing it exists, and that it's strict, formal, and XML-based, is usually enough.

Use SOAP when: you're integrating with an existing enterprise system that requires it, or you genuinely need its formal guarantees. For anything new and modern, REST or GraphQL will almost always serve you better.

Everything so far follows the same rhythm: the client asks, the server answers, then it's over. But some things need a live, two-way connection — a chat message arriving, a stock price ticking, a multiplayer game, a collaborative document updating as someone else types. You can't have the client constantly asking "anything new? anything new?"

WebSockets open a single, lasting connection that stays open, so messages can flow both ways at any time. The server can push to the client the instant something happens, without being asked.

Use WebSockets when: you need real-time, server-initiated updates — chat, live dashboards, notifications, games, collaborative editing. For everything else (most APIs), the simpler request/response styles are a better fit.

Here's the whole course on a single screen. When in doubt, start at the top.