What Is an API and How Does It Work? A Plain-English Guide

An API is an interface that programs use to exchange data and commands with each other. Thanks to APIs, a weather app pulls in the forecast, an online store accepts payments, a Telegram bot sends a message, and a website shows the current exchange rate.

Users usually never see the API: they tap a button, and the app reaches out to the right service on its own and gets back a result. Let's break down what happens under the hood, what an API request is made of, and why almost no modern service would work without APIs.

What is an API

API stands for Application Programming Interface.

The easiest way to picture an API is to think of a waiter in a restaurant:

• you pick a dish from the menu;
• the waiter takes your order to the kitchen;
• the kitchen prepares the dish;
• the waiter brings the finished result back to you.

In this analogy, you never step into the kitchen and you have no idea exactly how the dish is made. All you need to do is place your order following a set of clear rules. An API works the same way: one program sends a request, another performs an action and returns a response.

For example, a flight schedule website doesn't store data about every aircraft on its own. It can send a request to an airline's API and get back up-to-date information: departure time, flight number, status, and terminal.

How an API works

A web API generally follows a request → processing → response pattern.

1. The app sends a request to the API's address.
2. The API checks who's making the request and whether they have access.
3. The server processes the command: it looks up data, creates an order, sends a message, or performs some other action.
4. The server builds a response.
5. The app receives the response and shows the result to the user.

Say an app wants to fetch exchange rate data. It sends a request:

GET https://api.example.com/v1/rates?base=RUB

The server might respond like this:

{
  "base": "RUB",
  "rates": {
    "USD": 0.0127,
    "EUR": 0.0117
  },
  "updatedAt": "2026-07-05T12:00:00Z"
}

The app reads this JSON and displays the relevant numbers to the user in a friendly interface.

What makes up an API request

Most API requests have a few core parts.

1. URL and endpoint

URL — the server's address.
Endpoint — a specific point in the API responsible for a particular task.

For example:

https://api.example.com/v1/users/42

Here:

• https://api.example.com — the API's address;
• /v1 — the API version;
• /users — the users section;
• /42 — the specific user with ID 42.

A single API can have dozens of endpoints: for users, orders, products, messages, payments, and other entities.

2. HTTP method

The method indicates exactly what you want to do with the data.

For example, two requests can hit the same endpoint but do completely different things:

GET /v1/orders/125

Retrieves order #125.

DELETE /v1/orders/125

Attempts to delete order #125.

3. Parameters

Parameters help you refine a request. They're often passed right in the URL after a ? sign.

GET /v1/products?category=phones&limit=20

In this example, the API should return up to 20 products from the phones category.

There are also path parameters:

GET /v1/products/128

Here, 128 is the ID of a specific product.

4. Headers

Headers carry supporting information: the data format, language, authorization token, and other settings.

Example:

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

In many APIs, the most important header is Authorization. It tells the server who the request is being made on behalf of and whether that user has the necessary permissions.

5. Request body

The body is used when you need to send data to the server: creating an account, updating a profile, or placing an order.

For example, when creating a user:

{
  "name": "Anna",
  "email": "anna@example.com"
}

This kind of JSON is usually sent with a POST request.

What format an API returns data in

The most popular format is JSON. It's compact, human-readable, and easy to work with in JavaScript, Python, PHP, Go, and other languages.

Example of an API response:

{
  "id": 42,
  "name": "Anna",
  "plan": "premium",
  "active": true
}

XML used to be common, and you'll still find it in some systems today. But for modern web and mobile APIs, JSON has become the de facto standard.

API response codes

Along with the data, the server returns an HTTP status. It tells the app whether the request succeeded.

For example, if an API returns 401, the app usually prompts you to log in again. If it returns 429, the app can wait and retry the request later.

REST API, GraphQL, and webhooks — what's the difference

API is a broad term. REST, GraphQL, and webhooks are different ways to organize how services talk to each other.

REST API

REST is the most common approach. It has separate endpoints for different entities, and actions are carried out using HTTP methods.

Example:

GET /v1/users
GET /v1/users/42
POST /v1/users
DELETE /v1/users/42

REST is easy to understand, which is why it's widely used in websites, mobile apps, CRMs, and online stores.

GraphQL

GraphQL lets the client specify exactly which fields it needs. That's handy when there's a lot of data and you don't want to pull in anything extra.

For example, an app can ask for just a user's name and avatar rather than the entire profile.

Webhooks

A webhook works in the opposite direction: instead of your app asking the server "what's new?", the server sends a notification on its own whenever an event happens.

For example, a payment service can send a webhook to your site after a successful payment. That way the store finds out about the payment right away, without constantly polling for status.

How APIs protect data

An open endpoint with no restrictions is only suitable for public information — a list of countries or exchange rates, for example. As soon as an API deals with accounts, payments, or personal data, it needs protection.

The most common authorization methods are:

• API key — a permanent key for accessing the API;
• Bearer token — a temporary token passed in the Authorization header;
• OAuth 2.0 — secure sign-in through a third-party service such as Google or Telegram;
• JWT — a token that carries user data and an expiration time.

The golden rule: never store a secret API key in website code that loads in the browser. Other users would be able to see it. Secret keys belong on the server or in secure environment variables.

A simple API example in JavaScript

Below is a typical request from a website or app. The code sends a request, checks the response, and prints the data it gets back.

async function getUser(userId) {
  const response = await fetch(
    `https://api.example.com/v1/users/${userId}`,
    {
      headers: {
        Authorization: `Bearer ${process.env.API_TOKEN}`,
        Accept: "application/json"
      }
    }
  );
 
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }
 
  return response.json();
}
 
getUser(42)
  .then((user) => console.log(user.name))
  .catch((error) => console.error(error.message));

In a real project, the API address, the key, and the error handling will depend on the specific service. But the basic logic is almost always the same: send the request, check the status, parse the JSON, handle any errors.

Where APIs are used every day

APIs are at work in most of the services you use every day:

• a banking app shows your balance and transaction history;
• a marketplace pulls in data about products, shipping, and payments;
• a website logs users in through Google, Apple, or Telegram;
• a Telegram bot sends messages and accepts commands;
• a ride-hailing app gets coordinates, routes, and trip prices;
• a website displays weather, maps, exchange rates, or reviews;
• a VPN service can use an API to create a connection, hand out a configuration, and show your subscription status in your account dashboard.

Users only ever see buttons and screens, but behind them API requests are constantly flowing back and forth.

Common mistakes when working with APIs

Wrong URL or method

If the endpoint is wrong, the server will usually return 404. If you send a GET instead of a POST to create data, the API might respond with 405 Method Not Allowed or some other error.

No authorization

A 401 Unauthorized error means the token is missing, expired, or invalid. Check the Authorization header and the token's expiration time.

Not enough permissions

Even with a working token, you can still get a 403 Forbidden. For instance, a regular user can't delete someone else's account, and a test key has no access to live payments.

Too many requests

APIs often have limits to protect the service from being overloaded. When you hit 429 Too Many Requests, don't fire off the request again every millisecond — it's better to pause and retry with a gradually increasing interval.

Trusting data without checking it

Never assume that data from an external API is always correct. Validate field types, required values, and errors. This matters especially for payments, orders, and user data.

Bottom line

An API is an agreement that programs use to talk to one another. One system sends a well-defined request, another returns a structured response. Because of that, websites, apps, bots, and services can tap into each other's data and capabilities without ever accessing how the other one works inside.

To start working with an API, you really only need to get comfortable with five things: URLs, HTTP methods, parameters, authorization, and JSON. From there, it all comes down to the documentation of the specific service.

More tech guides →