APIs, or Application Programming Interfaces, are everywhere. They’re how your banking app talks to your bank, how Slack tells you someone mentioned you, or how your smart thermostat reports the temperature at 3am to a server that’s never heard of you. But “API” is a broad umbrella and it covers a surprisingly wide family of technologies, each designed to solve a different problem.
Picking the wrong API is a bit like sending a text message when you need a signed contract. Both communicate, but one of them won’t hold up in court.
This is a map of the main ones, grouped by what they do.
Please note: this gets technical. Not deeply so, but enough that some sections may feel dry on first read. That’s intentional. Each entry is the shortest explanation of what the thing is and what it’s actually for
Group 1: Ask and answer
The classic request-response pattern. One side asks, the other answers.
What is a REST API?
A REST API is a way for two systems to exchange data over the web using standard HTTP Requests, essentially the same mechanics a browser uses to load a page. It uses URLs to identify resources (/users/42,/orders/latest) and standard verbs to act on them: GET to fetch, POST to create, PUT to update, DELETE to remove. The server responds with data, usually JSON, and the connection closes.
REST’s strength is universality. Almost every programming language, framework and developer on the planet understands it. Its weakness is that the server decides what you get: sometimes more data than you need; sometimes a frustrating second request to get the rest.
→ REST architectural constraints - Roy Fielding’s dissertation
What is GraphQL?
GraphQL is a query language for APIs that lets the client define the exact type and depth of data it wants in a single request. Where REST returns a fixed payload, GraphQL lets you write a query: “give me the user’s name, their last three orders and the thumbnail of each product.”. No over-fetching, no extra round-trips. The server exposes a schema; you query against it.
This is particularly useful in mobile apps where bandwidth matters. Or in complex front-ends pulling from many object types at once. The trade-off: GraphQL requires more upfront schema design and is harder to cache than REST. N+1 query problems lurk if you’re not careful with your resolvers.
→ graphql.org - official specification and documentation
What is gRPC?
gRPC is a high-performance remote procedure call framework that lets one service call functions on another as if they were local, using binary serialisation instead of text. Where REST sends JSON (human-readable, relatively verbose), gRPC sends Protocol Buffers. These have a compact binary format that machines parse significantly faster and with less bandwidth. You define your service interface in a .proto file; gRPC generates client and server code in your language of choice.
It’s designed for internal communication between services, not for a browser talking to a server. If REST is two people exchanging letters, gRPC is two computers exchanging compressed signals over a private line.
→ grpc.io - official documentation
→ Protocol Buffers language guide
What is SOAP?
SOAP (Simple Object Access Protocol) is a strictly-defined XML-based messaging protocol for exchanging structured information between systems, with built-in standards for security, authentication and error handling.
Nobody chooses SOAP for fun. It’s verbose, heavyweight and takes significantly more effort to implement than REST. But in environments where security and contractual correctness are non-negotiable - banking, healthcare, government interoperability - “rigid and guaranteed” beats “flexible and probably fine.”
Every SOAP message follows a defined envelope structure. WS-Security handles encryption and signing. WSDL files describe the contract between parties. You can validate a SOAP message like a legal document. That’s the point.
Group 2: Push and notify
These flip the usual model. Instead of your app asking “anything new?”, the server tells you when something happens. The efficiency gains are significant. So are the new failure modes.
What is a Webhook?
A Webhook is an HTTP callback. You register a URL and a third-party system sends an HTTP POST to that URL the moment a specified event occurs. A payment succeeds, a form is submitted, a build finishes: your server gets a POST with the event payload and acts on it. No polling, no wasted requests.
Webhooks are elegant but unforgiving. If your endpoint is down when the event fires, you miss it. There’s no built-in retry or queuing. Most providers implement their own retry logic, but you’re relying on theirs, not your own. Fine for low-stakes notifications but worth thinking carefully about for anything business-critical.
→ webhook.site - test and inspect webhooks
What is SSE?
SSE (Server-Sent Events) is a browser API that opens a persistent, one-way HTTP connection from server to client, allowing the server to push a stream of updates without the client polling.
The client makes a single request. The server keeps the connection open and streams events down it as they occur. SSE is how AI chat interfaces deliver responses word by word rather than waiting to send everything at once. It’s also a natural fit for live dashboards, notification feeds and progress indicators.
The key distinction from WebSocket is that it’s one direction only. The server broadcasts. You receive. If you need the client to send messages back, you’ll need a separate mechanism. Or WebSocket.
→ MDN: Using server-sent events
What is WebSocket?
WebSocket is a protocol that establishes a persistent, full-duplex connection between client and server, allowing both sides to send messages at any time without re-establishing the connection.
This is what powers live chat, multiplayer games, collaborative document editing, and financial trading interfaces. The connection handshake happens once over HTTP, upgrades to WebSocket and stays open. Either party can push a message at any moment. No request-response cycle, no overhead of reconnecting for each exchange.
The cost is complexity. Managing connection state, handling reconnections gracefully and scaling across multiple server instances all require deliberate engineering. Don’t use WebSocket for things SSE or polling would handle adequately.
→ RFC 6455 - The WebSocket Protocol
Group 3: Queue and route
Less about direct communication, more about making sure messages get where they need to go: reliably, at scale, even when things go wrong. This is the boring infrastructure that makes everything else dependable.
What is EDA?
EDA, or Event-Driven Architecture, is a design pattern where services communicate by emitting and consuming events rather than calling each other directly. When something happens, like when an order is placed or a user changes their email, an event is published to a broker. Any service that cares about that event subscribes and reacts independently. The publisher doesn’t know or care who’s listening.
This decoupling makes systems resilient and scalable: services can be deployed, updated or fail without bringing each other down. The downside is observability. Understanding the full flow of a transaction across a distributed event-driven system requires tooling - tracing, event logs, schema registries - that tight coupling makes unnecessary. You trade coordination overhead for operational complexity.
EDA is a pattern, not a technology. It’s typically implemented using AMQP brokers (RabbitMQ, Azure Service Bus) or log-based platforms (Apache Kafka, AWS Kinesis).
→ AWS: What is event-driven architecture?
What is AMQP?
AMQP (Advanced Message Queuing Protocol) is an open standard for message-oriented middleware that guarantees message delivery between systems, even when the recipient is temporarily unavailable. Messages are published to a broker, which queues and routes them to the appropriate consumer. A message is only discarded once the consumer has explicitly acknowledged receipt. If the consumer is down, the message waits. Nothing is silently lost.
AMQP is what you reach for when the cost of a missed message is high such as in financial transactions, order processing, or inter-service communication in regulated industries. RabbitMQ is the most common implementation; Azure Service Bus and ActiveMQ also speak AMQP.
→ AMQP.org - the specification
What is MQTT?
MQTT (Message Queuing Telemetry Transport) is a lightweight publish-subscribe messaging protocol designed for unreliable networks and devices with constrained resources such as limited memory, processing power, or battery life.
A central broker routes messages between publishers and subscribers. Messages can be just a few bytes. Quality-of-service levels let you choose between “fire and forget” and “deliver exactly once”, depending on how critical the payload is.
It’s the standard backbone of the Internet of Things (IoT): the protocol running underneath smart meters, industrial monitors, connected vehicles, environmental sensors, and the thermostat whispering its temperature to the cloud every 30 seconds. Where AMQP is enterprise-grade infrastructure, MQTT is designed to run on a microcontroller with 256KB of RAM.
Group 4: Structured exchange
What is EDI?
EDI (Electronic Data Interchange) is the computer-to-computer exchange of standard business documents like purchase orders, invoices, shipping notices, etc, in a pre-agreed machine-readable format.
Both parties conform to a strict schema (ANSI X12, EDIFACT, or similar) so that any compliant system can parse the document correctly without human intervention. No interpretation is required. No ambiguity is permitted. A retailer sending an 810 invoice knows the supplier’s system will read it correctly, regardless of what software either party runs.
EDI predates the modern web by decades. It’s unglamorous, expensive to integrate and notoriously painful to debug. It also quietly underpins most of UK retail and manufacturing: if you supply Tesco, Sainsbury’s, or any major automotive manufacturer, you’re almost certainly sending EDI messages today, whether you know it or not. GS1 UK maintains the standards. The supermarkets enforce them by contract.
→ X12.org - ANSI X12 standards body
Closing thoughts
The instinct when confronted with a new integration requirement is often to reach for whatever you already know - REST because it’s familiar, WebSocket because it sounds impressive. But the right choice usually comes from the nature of the problem: who initiates the communication, how often, whether delivery matters more than speed, and whether machines or humans are ultimately at either end.
None of these technologies is universally superior. REST won’t tell you when something changes. WebSocket is overkill for a one-time data fetch. SOAP is painful right up until it’s the only thing your compliance team will sign off on. MQTT has no business on a server with unlimited memory and a gigabit connection. It belongs on the sensor attached to a pipe in a basement somewhere.
They’re different answers to different questions. Knowing which question you’re actually asking is the first step to choosing well. And not blaming the API when you pick the wrong one.