How APIs Actually Travel Between Systems
Source: Dev.to
Introduction
So far, we’ve talked about APIs as a way for systems to communicate.
But here’s an important clarification.
An API defines what systems say to each other. Network protocols define how those messages travel.
Let’s discuss some of the most common ways messages move across the network.
Think of APIs as the language. Think of protocols as the roads, vehicles, and traffic rules.
HTTP – the basic conversation
HTTP is the most common way applications talk over the internet. When you open a website or an app loads data, it usually uses HTTP underneath.
How it behaves
- One side sends a message
- The other side replies
- Conversation ends
It’s like sending a letter and waiting for a reply. This works well for:
- Loading pages
- Fetching data
- Simple request–response communication
HTTPS – HTTP with a lock
HTTPS is the same as HTTP, but secured. Think of it like sending the same letter, but inside a locked envelope. Only the sender and receiver can read it.
That’s why HTTPS is used for:
- Login systems
- Payments
- Any sensitive data
From an API point of view, nothing changes in behavior. Only privacy and safety improve.
WebSocket – keeping the call open
WebSocket is different. Instead of sending a message and closing the connection, it keeps the line open.
It’s like a phone call:
- Both sides stay connected
- Both can speak anytime
This is used when messages need to flow both ways and updates must be instant.
Examples
- Live chat
- Real-time notifications
- Live dashboards
APIs using WebSockets don’t “ask again and again”. They listen continuously.
TCP – slow but reliable delivery
TCP is about reliability. Imagine sending fragile items through a courier service that:
- Confirms delivery
- Resends if something is lost
- Keeps things in order
That’s TCP. Most APIs rely on TCP underneath because:
- Messages arrive correctly
- Nothing is lost silently
It’s slower than some options, but trustworthy.
UDP – fast but no guarantees
UDP is the opposite approach. It sends messages quickly, without checking if they arrived.
Imagine shouting information across a room: some people may miss it, but it’s fast.
Used where speed matters more than perfection
- Video calls
- Live streaming
- Online games
APIs rarely use UDP directly, but systems built on real‑time data often do.
HTTP/3 (QUIC) – modern and faster roads
HTTP/3 is a newer version of HTTP that runs on top of UDP.
The idea
- Reduce delays
- Recover faster from network issues
It’s useful for:
- Mobile apps
- IoT devices
- Real‑time experiences
From the API point of view, this mostly happens behind the scenes.
SMTP and FTP – special‑purpose messengers
Some protocols exist for very specific jobs.
- SMTP – designed for email.
- FTP – designed for file transfers.
They are not general API communication tools, but they still represent structured system‑to‑system communication and follow strict rules, just like APIs do.
Conclusion
APIs don’t float magically between systems. They travel using protocols like:
- HTTP / HTTPS
- WebSocket
- TCP / UDP
- HTTP/3 (QUIC)
- SMTP / FTP
Documentation tells you:
- Which protocol is used
- What behavior to expect
- Whether communication is instant or delayed
- Whether it’s one‑time or continuous
Without this clarity, teams guess, and guessing leads to fragile systems.
Why this matters for documentation
Good API documentation answers questions such as:
- Do I request or do I listen?
- Is this real‑time or delayed?
- Is this secure?
- Will I get a response immediately?
Without documentation, developers press buttons randomly, like using a TV remote without knowing what each button does.
Good documentation doesn’t just explain APIs. It explains how to communicate safely and correctly.