API


A	Application
P	Programming
I	Interface

An API is an interface that allows other programs to use functionality or data that you expose — without knowing how it is implemented.

In terms of distributed systems, an “API” usually means a Web API: an interface that is used over a network.

API use cases

Frontend ↔ Backend – your web or mobile app loads and stores data on the server.
Service ↔ Service – components of a distributed system talk to each other.
External services – weather, maps, payment, login, AI … (Data as a Service).

Software parts written in different languages can work together — as long as they agree on the same interface and the same protocol.

Example: weather data

Request:

GET https://www.7timer.info/bin/astro.php?lon=15.593063&lat=48.411018&ac=0&unit=metric&output=json

Response:

HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "product": "civil",
  "init": "2023070206",
  "dataseries": [
    { "cloudcover": 7, "temp2m": 21, "rh2m": "63%",
      "wind10m": { "direction": "W", "speed": 3 } },
    ...
  ]
}

Try it: paste the URL into your browser or run curl -i "<url>".

Many words – what is what?

“It’s a REST API that uses HTTP and JSON, described with OpenAPI.” These words are not alternatives — they describe different layers:

Layer	Question	Examples
API description	How is the API documented?	OpenAPI, AsyncAPI, `.proto`
Architectural style	How is the API designed?	REST, RPC, GraphQL, event-driven
Data format	How is the content encoded?	JSON, XML, Protobuf
Application protocol	Which messages are exchanged?	HTTP, WebSocket, MQTT
Transport	How do the bytes get there?	TCP, UDP, QUIC

Protocol vs. architectural style

Protocols …

define exactly how two processes exchange messages (format, meaning, order).
work between processes on different machines over a network.
are open to any technology or programming language.
have a clear, written specification (e.g. an RFC).

Architectural styles …

are design rules / ideas for building an API on top of a protocol.
have no strict specification — you can follow them more or less well.

	Protocol	Architectural style
Examples	HTTP, WebSocket, MQTT	REST, RPC, event-driven
Violate it?	it doesn’t work	it works, but it’s not that style
Analogy	grammar of a language	writing style (letter, poem, news)

🔑 REST is not a protocol — it is a way of designing an API that uses the HTTP protocol.

Ways of providing an API

REST

Architectural style (Roy Fielding, 2000) — built on HTTP.
Everything is a resource with its own URL; you use HTTP methods on it.

GET    /students/42
DELETE /students/42

Use: the default for most web APIs — simple, widely supported, cacheable.

GraphQL

Query language for APIs (Facebook, 2015) — usually one endpoint over HTTP.
The client decides which fields it wants.

{ student(id: 42) { name grades { subject value } } }

Use: frontends that need flexible data from many sources in one request.

gRPC

RPC framework (Google, 2015) — call functions on a remote server like local ones.
Contract in a .proto file, binary Protobuf messages over HTTP/2.
Use: fast, strongly typed communication between services (microservices).

SOAP

XML-based messaging protocol (W3C), usually over HTTP; described with WSDL.
Use: older enterprise and government systems (banks, insurance) — you will still meet it.

WebSocket

Protocol for a permanently open, bidirectional connection (starts as HTTP).
Use: real-time data — chat, live scores, multiplayer games, dashboards.

Webhooks

A pattern, not a protocol: the provider sends an HTTP POST to your URL when something happens.
Use: notifications — “payment received”, “new commit pushed”.

Message brokers (MQTT, AMQP, Kafka)

Publish/subscribe: senders publish to a topic, receivers subscribe (→ Distributed-Systems).
Use: IoT (MQTT), decoupled background processing, event streaming.

MCP – Model Context Protocol

Open protocol (Anthropic, 2024) based on JSON-RPC.
Lets AI applications (e.g. Claude, ChatGPT, IDE assistants) connect to external tools and data in a standardised way.
An MCP server exposes tools, resources and prompts; the AI app is the client.
Use: give an AI model access to your files, databases or APIs — “a USB-C port for AI”.

Overview

Name	What is it?	Runs on	Format	Typical use
REST	architectural style	HTTP	mostly JSON	web APIs
GraphQL	query language + spec	HTTP	JSON	flexible frontends
gRPC	RPC framework / protocol	HTTP/2	Protobuf	service ↔ service
SOAP	messaging protocol	HTTP	XML	legacy enterprise
WebSocket	protocol	TCP	text / binary	real-time
Webhooks	pattern	HTTP	mostly JSON	event notifications
MQTT / AMQP	protocols (pub/sub)	TCP	any	IoT, messaging
MCP	protocol	JSON-RPC over stdio / HTTP	JSON	AI ↔ tools

Usage

From the Postman State of the API Report 2025:

Summary

An API is an interface for programs; a Web API is used over the network.
Keep the layers apart: transport → protocol → data format → style → description.
Protocols (HTTP, WebSocket, MQTT, MCP …) are strict message specifications.
Architectural styles (REST, RPC, event-driven …) are design ideas on top of protocols.
REST, GraphQL and gRPC all usually travel over HTTP — they differ in design.

Check your understanding

Explain the difference between a protocol and an architectural style. Give two examples of each.
What is wrong with the sentence “Our API uses REST instead of HTTP”?
Assign each term to its layer: TCP, REST, JSON, HTTP/2, OpenAPI, Protobuf, MQTT, QUIC.
Which technology would you choose — and why?
- a chat app that shows new messages instantly
- 50 internal microservices that call each other thousands of times per second
- temperature sensors in every classroom
- an AI assistant that should be able to read your school’s timetable

Deep Thought

Explorer

API-v2

API