Types of APIs

An API is how one program asks another for data or asks it to do something. REST, SOAP, gRPC and WebSockets all do that job, but they make different trade-offs between readability, strictness, speed and how long a conversation lasts, and picking the wrong one makes a system harder to build than it needs to be.

What every API has in common

Whatever the style, an API is a contract. One side, the client, sends a message in an agreed format. The other side, the server, understands that format and replies. The contract covers where to send the message, what it must contain and what comes back.

The four styles in the video differ on three questions:

• Is the message human-readable text (JSON, XML) or compact binary?
• Is the shape of every message written down and enforced, or only documented?
• Is each exchange a single request and response, or does the connection stay open?

Each style below answers them differently.

REST: resources over plain HTTP

REST is an architectural style rather than a protocol. A REST API exposes resources (users, orders, cat photos) at URLs, and you act on them with standard HTTP methods: GET to read, POST to create, PUT or PATCH to update, DELETE to remove.

Reading a user looks like this:

GET /users/42 HTTP/1.1
Host: api.example.com
Accept: application/json

And the server replies with a status code and, usually, JSON:

{
  "id": 42,
  "name": "Kitty",
  "plan": "pro"
}

A few properties make REST the default for most web apps:

• It reuses the web. URLs, methods, status codes (200, 404, 500) and caching headers are all standard HTTP, so browsers, proxies and CDNs already understand them.
• It is easy to debug. You can call it with curl, read the response in the browser's Network tab and see what went wrong.
• It is stateless. Each request carries everything the server needs, such as an auth token, so any server behind a load balancer can answer it.

The cost is that REST has no built-in contract. Unless you add one, such as an OpenAPI document, nothing stops a field changing type between releases. A screen that needs data from several resources can also end up making several round trips.

SOAP: a formal XML contract

SOAP is a protocol with strict rules. Every message is an XML document wrapped in an envelope, with an optional header for things like security and a body for the call itself:

<soap:Envelope
  xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Header>
    <!-- security token, transaction id -->
  </soap:Header>
  <soap:Body>
    <GetBalance>
      <AccountId>12345</AccountId>
    </GetBalance>
  </soap:Body>
</soap:Envelope>

A SOAP service is usually described by a WSDL (Web Services Description Language) file, an XML document listing every operation and the exact shape of its inputs and outputs. Tools read the WSDL and generate client code, so both sides agree on the contract before any message is sent.

On top of that sit the WS-* standards. WS-Security defines how to sign and encrypt parts of a message, so the message itself stays protected even as it passes through intermediaries. That, plus the strict contract, is why SOAP is still common in banking, insurance, government and other large enterprise systems where integrations last for years and auditors care about every field.

The ceremony has a price. XML is verbose, the tooling is heavy and a simple call needs a lot of boilerplate. Few teams choose SOAP for a new public API today; most meet it when they integrate with an older system that already speaks it.

gRPC: binary, typed and fast

gRPC is a framework for calling functions on another machine as if they were local. You describe the service once in a .proto file using Protocol Buffers:

syntax = "proto3";
 
service Orders {
  rpc GetOrder (OrderRequest) returns (Order);
}
 
message OrderRequest {
  int32 id = 1;
}
 
message Order {
  int32 id = 1;
  string status = 2;
}

The gRPC tools generate client and server code from that file in many languages, so a Go service and a Python service share one typed contract. In a statically typed language, passing the wrong type for a field fails at compile time instead of in production.

On the wire, messages are encoded as compact binary rather than text, and gRPC runs over HTTP/2, which can carry many calls at once on one connection and supports streaming in both directions. The result is small messages and low overhead, which is why gRPC is a popular choice for traffic between microservices inside one system.

The downside is that you can't read a gRPC message by eye or test it with a plain curl call; you need tools that understand the .proto file. Browsers can't speak native gRPC either, so a web front end needs a proxy layer such as gRPC-Web, or a REST API in front.

WebSockets: a connection that stays open

With REST, the client always speaks first. If a chat app wants new messages, it has to keep asking 'anything new?', which is called polling. Most of those requests come back empty, and a new message still waits until the next poll.

A WebSocket fixes that. The browser opens an ordinary HTTP request asking to upgrade the connection. The server answers 101 Switching Protocols, and from then on the same connection stays open and either side can send a message at any moment. Here is that switch, from polling to an open connection:

In the browser, the WebSocket API is small:

const ws = new WebSocket("wss://chat.example.com");
 
ws.onopen = () => ws.send("hi");
 
ws.onmessage = (event) => {
  console.log("new message:", event.data);
};

That makes WebSockets the natural fit for chat, multiplayer games, live dashboards, collaborative editors and anything else where the server needs to push updates the moment they happen.

The trade-off is state. Every open connection holds memory on a server, so a busy app may hold tens of thousands at once, and load balancers must support long-lived connections. When a server restarts, every client has to reconnect, so client code needs reconnect logic. For updates that only ever flow from server to client, such as a live score, Server-Sent Events can be a lighter option.

Choosing between them

Most systems of any size use more than one. Take a food delivery app:

A reasonable default is REST for anything public, then reach for the others when there's a clear reason: WebSockets when the server must push in real time, gRPC when internal services call each other heavily, and SOAP when an existing partner requires it. GraphQL is another style you'll meet, where the client asks for exactly the fields it needs in one request; it suits screens that would otherwise make many REST calls.

Common mistakes

• Polling when you need real time: asking every second wastes requests and still adds delay. If updates must arrive instantly, use a WebSocket or Server-Sent Events.
• Using WebSockets for everything: a form submission or a page of products is a single request and response. Holding a connection open for it adds state and complexity for nothing.
• Exposing gRPC straight to browsers: they can't call it natively, so plan for gRPC-Web or a REST layer in front.
• Treating REST as 'any JSON over HTTP': sending everything as POST /doThing throws away caching, clear status codes and predictable URLs, which are the reasons to use REST in the first place.
• Assuming SOAP is secure by default: its standards make strong message-level security possible, but only if the service signs and encrypts its messages and runs over HTTPS.

If a browser calls your API from another site, it also has to deal with CORS, whichever style you choose.

Key takeaways

• An API is a contract for how programs talk; REST, SOAP, gRPC and WebSockets differ in format, strictness and how long a connection lasts.
• REST uses URLs and HTTP methods with readable JSON, and is the right default for most web apps.
• SOAP wraps strict XML messages in an envelope with a formal contract, and lives on in banks and large enterprises.
• gRPC sends typed, binary Protocol Buffers messages over HTTP/2 with generated code, which makes it fast for microservices but hard to read.
• WebSockets keep one connection open so either side can send at any time, which suits chat, games and live dashboards.