Every arrow in this diagram is a conversation. The API is what makes sure both sides speak the same language.

APIs Explained: Everything I Wish Someone Had Told Me Earlier

A final-year student’s attempt to explain the thing that confused me for way too long.

When I started my internship at Maersk, one of the world’s largest shipping and logistics companies, I quickly realized something: almost every system, tool, and dashboard I worked with was talking to something else. Data flowing in, responses going out, services quietly handing off information behind the scenes.

The glue holding all of it together? APIs.

I’ll be honest, I had heard the term a hundred times before and never truly got it. Every explanation I came across either went over my head or felt too abstract to stick. It only clicked when I saw it working in real systems.

So this is my attempt to explain APIs the way I wish someone had explained them to me. No jargon overload, no assuming you already know things. Just the stuff that actually matters.

Okay, What Even Is an API?

API stands for Application Programming Interface.

I know, that doesn’t help. Let me try again.

You know how when you’re ordering food on Zomato and a little map shows up telling you exactly where your delivery guy is? Zomato didn’t build that map. Google Maps did. But Zomato also can’t just break into Google’s servers and grab that data. So instead, it sends a polite request through something called Google Maps’ API, and Google Maps sends back exactly what’s needed.

The API is basically the middleman. It lets two completely different systems talk to each other without either of them having to know how the other one works internally.

That’s it. That’s the core idea. Everything else is just details on top of that.

Zomato App  -->  [Request]   -->  API  -->  [Request]   -->  Google Maps
Zomato App  <--  [Response]  <--  API  <--  [Response]  <--  Google Maps

How Does It Actually Work?

Every time an API is used, it follows the same four steps:

1. Request -Your app sends a request to an API endpoint
2. Processing -The API forwards it to the right server
3. Response -The server does its thing and sends data back
4. Delivery -You get your answer

Think of it like ordering at a restaurant. You tell the waiter what you want (request), the waiter goes to the kitchen (processing), the kitchen makes it (response), and the waiter brings it to your table (delivery). The API is the waiter.

API Keys: Why Not Everyone Gets In

Some APIs are free for anyone to use. But a lot of them aren’t, and that’s where API keys come in.

An API key is basically a secret password given only to approved developers. It tells the server “hey, this person is allowed to use this.”

If an API is completely free, there’s usually no key needed. But most real-world APIs that have some value will require a key, and in many cases you might even have to pay for it.

The whole point is two things: keeping the API secure (not letting random people abuse it) and monitoring usage (tracking what’s being requested, catching suspicious activity).

Where Do We Actually See This in Real Life?

The easiest example is something most of us have clicked without thinking about: “Sign in with Google.”

When some new app lets you register using your Google account, that app isn’t checking your credentials itself. It’s calling Google’s API, letting Google do the verification, and then just fetching your basic details from Google once you’re confirmed. The app doesn’t need to build its own login system from scratch.

At Maersk, I got to see this at a much bigger scale. Different systems for shipment tracking, port operations, customer data, logistics planning, all separate, all talking to each other through APIs. It genuinely changed how I thought about software.

Types of APIs (This Is the Important Part)

Not all APIs work the same way. Different situations call for different approaches, and this is what most tutorials skip explaining properly.

1. REST API

This is the one you’ll encounter the most. REST stands for Representational State Transfer, but honestly just remember it as the standard way most apps communicate over the internet today.

It works over HTTP (the same protocol your browser uses), sends and receives data in JSON format, and follows a simple client-server model.

Client  -->  HTTP request to an endpoint URL  -->  Server
Client  <--  JSON response                    <--  Server

The really important thing about REST is that it’s stateless. This means the server has no memory of your previous request. Every single call is treated as brand new. That might sound like a limitation but it’s actually what makes REST so scalable. Since the server doesn’t need to remember anything, it can handle millions of requests at the same time without getting overwhelmed.

It’s also platform independent, meaning iOS, Android, and web apps can all talk to the same REST API without any issues.

2. SOAP API

SOAP stands for Simple Object Access Protocol. It’s older than REST and a lot more strict about how things are done.

Where REST uses JSON, SOAP uses XML. Where REST is flexible about which protocol it runs on, SOAP mostly sticks to HTTP/HTTPS but can also run on SMTP, TCP, and others.

It’s more complex to work with, but here’s why it still exists: SOAP guarantees delivery. It has built-in error handling and reliability standards that REST doesn’t enforce. That’s why industries like banking, healthcare, and large-scale logistics still use it. When you absolutely cannot afford for something to go wrong, SOAP is trusted.

A SOAP message has three main parts:

• Envelope -wraps the entire message
• Header -optional, carries metadata
• Body -the actual request or response content

3. gRPC

gRPC was built by Google and it is fast. We’re talking roughly 7 times faster than REST.

The reason? REST sends text-based JSON. gRPC converts everything into a compact binary format using something called Protocol Buffers. Binary is much smaller and faster to process than text.

It also supports four different communication patterns, which gives it a lot of flexibility:

• Simple request-response (same as REST)
• Server streaming, where the server sends continuous updates
• Client streaming, where the client sends a continuous stream of data
• Bidirectional streaming, where both sides are sending data to each other in real time

Netflix and Uber use gRPC internally. If you ever work on a system where speed and efficiency really matter, this is worth knowing.

4. GraphQL

REST APIs have two common problems that can be really annoying to deal with.

The first is over-fetching: you ask for one thing and get back a massive object full of data you don’t need. The second is under-fetching: you don’t get enough in one call and have to make multiple requests to piece together what you actually wanted.

GraphQL fixes both of these. Instead of hitting different endpoints for different things, there’s just one endpoint. You write a query describing exactly what you want:

query {
  user(id: 123) {
    username
    birthday
  }
}

One request. One endpoint. Only the fields you asked for. Nothing extra.

GitHub, Pinterest, and Shopify all use GraphQL. It’s especially useful when your frontend and backend are evolving quickly and you don’t want to keep creating new endpoints for every new screen.

5. Webhook API

Regular APIs work on a pull model. You ask for data, you get data.

Webhooks work on a push model. Instead of your app constantly asking “has anything changed?”, you set up a callback URL and the other service automatically notifies you the moment something happens.

So instead of polling a payment service every few seconds asking “was the payment successful?”, you give them a URL. The moment the payment goes through, they send a POST request to that URL with all the details. No unnecessary requests, no wasted server resources.

GitHub fires webhooks when new code is pushed. Shopify fires them when a new order comes in. This is actually why webhooks are sometimes called “reverse APIs” the flow is backwards compared to what you’re used to.

6. WebSocket API

Standard HTTP is stateless and always client-initiated. The client asks, the server answers, and the connection closes. That’s fine for most things but terrible for anything real-time.

WebSockets solve this by opening a persistent two-way connection between the client and server. It starts with a one-time handshake over HTTP, and after that both sides can send messages to each other whenever they want without waiting to be asked.

This is what powers live chat applications, multiplayer games, collaborative tools like Google Docs, and live data feeds. Once the connection is open, the server can push data to you the instant something changes.

7. WebRTC

WebRTC stands for Web Real Time Communication and it’s a bit different from everything else on this list.

Instead of going through a server to exchange data, WebRTC allows direct peer-to-peer communication between two browsers. The data doesn’t even pass through a central server.

It also uses something called adaptive bitrate streaming, which automatically adjusts the quality of audio or video based on your internet speed. That’s why video calls don’t always crash completely when your connection gets bad they just get a bit pixelated instead.

Google Meet, live streaming platforms, and online voice chat in games are all built on WebRTC.

HTTP Methods: The Vocabulary You Need

When you’re working with REST APIs especially, every action maps to an HTTP method. These correspond to the classic CRUD operations:

MethodWhat It DoesIdempotent?GETRead / fetch dataYesPOSTCreate something newNoPUTReplace something entirelyYesPATCHUpdate part of somethingNoDELETERemove somethingYes

One thing worth understanding is idempotency. An operation is idempotent if doing it multiple times gives the same result as doing it once. GET is idempotent because asking for the same data ten times gives you the same answer. POST is not, because sending the same POST request twice might create two separate records.

PUT vs POST trips a lot of people up. PUT is idempotent because you’re replacing a specific resource with a specific thing. POST is not because every call might create a new resource.

A Bit on API Security

APIs are powerful, which means they can also be exploited if not protected properly.

A few things that keep APIs safe:

CORS (Cross-Origin Resource Sharing) handles which external domains are allowed to call your API. By default, browsers block requests to APIs from different domains (this is called the Same-Origin Policy). CORS headers explicitly whitelist the ones you trust.

SQL and NoSQL injection is when malicious user input gets passed directly into a database query. Always validate and sanitize input before it goes anywhere near your database.

Firewalls sit in front of the API and filter out malicious traffic before it even reaches your server.

Status Codes: What the Server Is Actually Saying

Every API response comes with a three-digit status code. Once you know what these mean, debugging becomes so much less painful.

CodeWhat It Means200 OKEverything worked201 CreatedNew resource was successfully created204 No ContentWorked fine, but nothing to send back400 Bad RequestSomething in your request is wrong401 UnauthorizedMissing or wrong credentials403 ForbiddenYour credentials are fine but you don’t have access404 Not FoundThat resource doesn’t exist429 Too Many RequestsYou’ve hit the rate limit, slow down

The 4xx codes mean the problem is on your end. The 5xx codes (like 500 Internal Server Error) mean the problem is on the server’s end. That distinction alone saves a lot of time when you’re debugging.

That’s Pretty Much It

If you made it this far, you now know more about APIs than I did walking into my internship. And honestly, that’s a solid foundation.

APIs are everywhere. Whether it’s the apps you use every day or the backend systems powering some of the biggest companies in the world, everything is connected through them. Understanding how that connection works puts you in a really good place as a developer.

I’m currently in my final year, actively learning and documenting what I pick up along the way. If you found this useful or have anything to add, feel free to reach out on LinkedIn. I’d love to hear from you.

Happy to help if any of this was confusing. That’s the whole point.