APIs for Beginners: What They Are and How They Work | HackerNoon

API.

This word pops up in every IT video, every job post, every developer conversation.

But when you Google it, you get tons of complicated definitions about “Application Programming Interfaces” — and your brain just melts.

Today, I’ll explain what an API actually is — in a way that you’ll definitely understand: with simple, real-life examples, interesting storytelling, and clear visuals.

In just a few minutes, you’ll know exactly what an API is and even how to create your own.

A Real-Life Situation

Imagine we want to launch our own marketplace. The idea is simple: hundreds of different suppliers can list and sell their products on our platform, and buyers can find anything they need in one place — kind of like Amazon or eBay.

For buyers, of course, we’ll make a nice website. That’s our user interface (UI).

Want to find a product? Here’s the search bar.

See something interesting? Click “Add to cart.”

Ready to buy? Click “Checkout.”

All these elements — buttons, menus, input fields — are a human-friendly control panel for our application.

When users click them, they give commands to a complex program — our marketplace — and that program runs a bunch of code that handles how orders are created, how search works, and so on.

But users don’t need to dive into the code or understand how it all works. They just click simple buttons to send commands. So, the buyer has this visual interface to communicate with the app.

But what about the suppliers?

Most suppliers already have their own software for managing their products — tracking stock, prices, discounts, etc. Some use Excel, others use Google Sheets, and some have custom systems. Now, they want to list their products on our platform. But they have thousands of goods!

n We could create a supplier portal for them — another website with buttons, just like the buyer’s one, but with functions like upload product, add discount, change category.

But the supplier would look at it and think:

Are you serious? I have 10,000 products already stored in my own system. You want me to sit for a month manually copying each product into your system through these buttons? That’s insane!

And he’s absolutely right. It’s slow, expensive, and guaranteed to produce mistakes.

So, what does such a supplier dream of? n

If only there were a way for my program to automatically send all my products directly to the marketplace in a split second!

How can we make that happen?..

That means the supplier doesn’t want to do it manually. He doesn’t need a human interface with buttons. He needs an interface for his program! So that his software could send commands to our marketplace — not him personally.

But his program doesn’t have eyes or hands. A graphical interface with buttons is useless to it. So we need a different kind of interface…

Wouldn’t it be nice if the supplier’s program could somehow connect over the internet to our marketplace and send product data directly?

Then we’d need to build into our marketplace some kind of special “sockets” or “ports” that other programs could “plug into.”

Each socket would handle a specific task.

• The first socket, for example, could handle adding new products. The supplier’s program “plugs in” to that socket and sends product data through it. Everything that comes through this socket is treated by our marketplace as a new product and added to the catalog.
• Another socket might handle updating discounts. If the supplier launches a sale, his program connects to that socket and sends info about which products have what discounts. The marketplace processes that data and updates the prices on the storefront.

Then sending data to the right socket is basically sending a command to our app.

Want to add a product? Connect to this socket and send product data. Want to set discounts? Connect to that socket. Our app performs the corresponding action for each connection.

So, API is exactly this — a set of such programmatic sockets that an application provides to the outside world.

Any app can expose such a set of “sockets” — that’s what we call an API (Application Programming Interface). It’s literally a programming interface — a set of ways to send commands to our app from the outside.

But unlike the user interface (UI), where commands come from people, here they come from other programs. That’s why it’s called a programming interface.

And that’s what “API” means — a way for programs to communicate automatically.

Now, the supplier’s inventory system can “plug into” our API and send product data by itself — no humans involved. But, of course, the data must be in a specific format that our marketplace can understand.

Such messages literally contain product information, and there are many text formats for that — but the most popular today is JSON. Here’s how the product data may look like in such a format:

{
  "title": "Crazy Hamster",
  "price": 1500,
  "quantity": 350
}

So now, when the supplier adds a new product in his system, it automatically forms a JSON message and sends it to our “socket.”

And not just one — it can prepare 10,000 of them at once, pack them into one large request, and send it. Our API receives it, processes all 10,000 products, and saves them — all in a second! No manual clicks needed.

How Do You Create Your Own API?

But what exactly is this “socket” in code? How do we developers actually make an API?

Inside our application, we write code. We have different functions that perform actions. For example, in our marketplace we can write a function addGoods().

function addGoods(goods) {
  database.save(goods);
}

This function takes a list of products as a parameter and saves them in the system. From our own code, we can easily call it — no problem.

But here’s the issue: this function lives inside our application. How can the supplier’s program call it? It can’t just reach into our code and execute our function.

n The supplier’s software is a completely separate program — on a different computer, maybe in another city, even written in another programming language!

You can’t just write code in that external program that calls a function inside our application. That line simply wouldn’t compile, because for the supplier’s app, our addGoods() function doesn’t exist — it’s defined elsewhere.

But how do we allow an external program to “call” our internal functions?

What if we give our function a public internet address? Our site already has one — say, marketplace.com. When you go to that address in a browser, you see the homepage.

But we could also create specific internet addresses for our functions.

For example: when you visit marketplace.com/products and hit Enter — our code triggers the addGoods() function.

So we “bind” this function to the /products path. If that path appears in the address, the app knows it should call that specific function.

And we can do the same for other functions:

For updating prices — /prices.

For getting reports — /reports.

Each function gets its own unique, public address. “Public” means that anyone on the internet could technically reach it.

And this public address for a specific function in our app is called an endpoint.

You can create such endpoints in any programming language using special frameworks. For example, in Java, you can use Spring. In Python, you can use Django. And so on.

Now, when our function has a public address, not only humans but also other programs can access it!

@address("/products")
function addGoods(goods) {
  //...
}

@address("/prices")
function updatePrice(price) {
  //...
}

@address("/reports")
function getReports() {
  //...
}

Note: this example uses a general pseudo-code. Specific annotations and ways of tying a function to a given address depend on a programming language and framework you use for you app.

In the example above, @address contains the specific address that is binded to the function below it. This is exactly the address that should be added to the URL when sending a request over the Internet in order to call the specific function in our marketplace.

But why do we need that? The thing is that now the supplier’s program can store this address as a simple text string in its code — everything will compile just fine.

Then it sends product data to that address over the internet using a networking library.

The data travels through the web, and when our marketplace receives it, it automatically triggers the linked function and passes the data into it — because the message was sent to that exact address.

So, the supplier’s program doesn’t need to interact with our marketplace code directly. It just uses the internet addresses of marketplace’s functions it needs to call in different situations.

And the goods array here is automatically packaged into JSON format when using a library for web communication. Then it’s passed through the network in this format and automatically turned back into an actual goods parameter and passed to addGoods() function on the other side.

Usually, the library or framework you use for this communication takes care of this automatically.

And that’s what an API really is: a set of public functions of your app that are available via the internet. It’s a way to control your software without buttons, purely through code.

So, your app gets a second interface: one for users (UI) and one for programs (API).

Who Can Use Our API?

So we’ve learned how our marketplace communicates with external programs through an API. But now comes the real mind-blower: even our own application internally consists of two separate programs that also communicate through an API!

What you see in your browser — all the buttons, product images, menus — is the frontend. That’s our storefront. It’s basically a visual layer of our app. Frontend code, usually written in JavaScript, loads into your browser and runs locally on your computer.

It’s lightweight and mainly responsible for visuals and interactivity. Usually, it doesn’t contain any real business logic. When you press a button, nothing major happens in the frontend itself — aside from animations or visual changes. In reality, the frontend just sends the user’s actions or input to another, second program.

Where? And why?

That second program is called the backend — the heart and engine of your app. It’s where all the main actions happen: handling payments, saving orders, searching products, and more. This backend runs on a powerful computer called a server, capable of handling large, heavy operations. For example, searching through thousands of products — that’s computationally heavy!

Your browser alone couldn’t handle that on the frontend. So you write a separate program, maybe in Java or Go, that contains all the core logic of your app.

The backend does the real work, but it’s invisible to the user — it sits “behind” the frontend. That’s where the names come from: front-end (in front) and back-end (in the back).

Now, the key question:

If the frontend is a program written in JavaScript and the backend is a completely different one — say, in Java — how do they talk to each other?

When you click “Buy,” how does that command reach the backend so the product is deducted from the database?

Of course — through the same API!

Our backend provides a set of “sockets” not just for external programs, but also for its own frontend. Because frontend is just another program!

And since it’s a program, it can also make requests to any API endpoint of our backend — just like the supplier’s system did earlier.

For example, when you open the homepage, the frontend immediately calls the backend’s endpoint /products/list, which is linked to a function that fetches all products.

The backend processes that request and sends back the product data. The frontend receives it and beautifully displays it on the page. When you click “Buy,” the frontend sends product info to the backend’s /orders endpoint, where the order and payment logic runs.

So, API is a universal communication method — not only between different apps, but also between the different parts of one large app.

It’s a fundamental principle behind almost every modern web service.

Conclusion

I hope this article helped you clearly understand what an API is!

Please press a like if it was helpful — it supports me in making more content like this.

And write in the comments which topics you’d like me to explain next in simple terms and with clear diagrams — I’ll definitely include them in future posts.

Thank you!