What Is an API? Explained Simply, With Real Examples (2026)

The word shows up everywhere. The weather app “pulls its data from an API”, the online store “has an API to the inventory system”, and every AI tool wants you to paste in an “API key”. If you don’t write code, you usually nod and hope nobody asks a follow-up question.

What is an API? An API (Application Programming Interface) is an agreed way for one program to ask another program for something — and an agreed shape for the answer. It is a contract: “If you ask me like this, I will answer you like that.” Humans use an interface with buttons; programs use an API.

This article explains it from the ground up: what actually travels over the wire during an API call, what endpoints, methods and status codes are, what an API key is for and why it must stay secret, how rate limits work — and why a website that has no API at all still receives hundreds of requests to /api/ every day. Every number here comes from measurements on our own server on October 12, 2026, not from documentation.

From AWS Developers, September 2026: a particularly good explanation of why companies hide their logic behind an API in the first place instead of building it twice for website and app.

What is an API — the short answer in five sentences

1. An API is an interface between two programs, not between a person and a program.
2. It defines which questions are allowed and what format the answer comes back in.
3. On the web this almost always runs over HTTP — the same protocol your browser used to load this page.
4. The answer is usually JSON, a plain text format for structured data.
5. Whoever offers the API stays in control: they decide who may ask, how often, and what they get to see.

The most important idea is in point 5. An API is not simply “access to the database”. It is the opposite: a door with a bouncer. The database itself stays hidden, and from the outside you can only ask exactly the questions the operator is willing to answer.

The restaurant analogy — and where it breaks

The best-known explanation goes like this. You sit in a restaurant (you are the calling program). The kitchen (the server holding the data) is off-limits. The waiter is the API: they take your order in a fixed form — from the menu — carry it to the kitchen and come back with the result.

That captures three things well:

• The menu is the documentation. What isn’t on it, you can’t order, however politely you ask.
• You don’t need to know how the kitchen works. Gas stove or induction, you don’t care. With an API you equally don’t care whether PostgreSQL, a spreadsheet or another service sits behind it.
• The kitchen can be rebuilt without anything changing for you — as long as the menu stays the same.

Where the analogy breaks: a waiter remembers who you are. Most web APIs do not. Every request stands on its own and has to carry everything the server needs to know — including proof of who you are. This is called stateless, and it is why your API key is sent with every single request, not just once at “login”.

What actually happens during an API call

Enough metaphors. Here is a real call. We ask the free weather service Open-Meteo for the current temperature in the Sauerland region of Germany:

curl "https://api.open-meteo.com/v1/forecast?latitude=51.37&longitude=8.38&current=temperature_2m"

The answer our server received on 2026-10-12 at 07:00 UTC (shortened):

{
  "latitude": 51.37532,
  "longitude": 8.400086,
  "generationtime_ms": 5.78,
  "elevation": 440.0,
  "current_units": { "temperature_2m": "°C" },
  "current": { "time": "2026-10-12T07:00", "temperature_2m": 4.5 }
}

4.5 °C. That’s all that happened — and that is exactly the point. No login, no interface, no ads. One program sends a line of text, another program answers with a few lines of text that can be processed directly.

Taken apart, the request looks like this:

How long a call takes — measured

We timed the call from our server in Germany. For the first five calls, curl broke the time down like this:

A second run of 20 calls right afterwards came in at 24 ms median (95% under 29 ms). Why the first calls took three times as long we can’t see from the outside — most likely the answer was already in the provider’s cache the second time. The server itself reports just under 6 ms of compute time in its generationtime_ms field.

For comparison: the same kind of request to a tiny API on the same machine (more on that in a moment) took 0.5 ms median over 200 repetitions. The gap between 0.5 and 24 ms is almost entirely network: distance, encryption, connection setup. That’s the first practical lesson about APIs: an third-party API call is roughly fifty times slower than a local function call — at best. If you loop over 1,000 products and call an API for each, you don’t wait half a second, you wait somewhere between 25 and 80.

The building blocks of a web API

Almost every API you meet on the web follows the REST style (Representational State Transfer). It isn’t a certified standard, it’s a set of conventions. Once you’ve understood them, you can read most APIs without working through the full documentation.

Endpoints: the addresses

An endpoint is a URL with a specific thing behind it. In a REST API these are typically things (nouns), not actions:

/todos          → all tasks
/todos/42       → task number 42
/users/7/orders → the orders of user 7

Methods: what you want to do with the address

What should happen to the thing is expressed by the HTTP method:

Rule of thumb: GET must never change anything. Links, messenger link previews and search engine crawlers call GET URLs without asking. If you build “delete” as a GET link, your data will eventually be deleted because a bot passed by.

Status codes: how it went

Every response carries a three-digit number saying whether it worked. The ones you’ll actually see:

Easy to remember: 4xx means something is wrong with your request. 5xx means something is wrong with the server. Resending the same request doesn’t help with 4xx. With 5xx and 429 it does — just please with a pause.

Headers and body: envelope and content

A request has two parts. The headers are like what’s written on an envelope: who you are (Authorization), what format you’re sending (Content-Type: application/json), what you want back (Accept). The body is the actual content — usually empty for GET, for POST for example the new task as JSON. If JSON is new to you, What is a JSON file explains the format and its traps from scratch.

Your own API in 16 lines

The fastest way to understand an API is to build one. The following program is a complete, working web API in Node.js — no framework, no library, 16 lines:

import http from 'node:http';
const todos = [{ id: 1, text: 'Write article', done: false }];
http.createServer((req, res) => {
  const send = (code, body) => { res.writeHead(code, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(body)); };
  if (req.url === '/todos' && req.method === 'GET') return send(200, todos);
  if (req.url === '/todos' && req.method === 'POST') {
    let raw = ''; req.on('data', c => raw += c);
    req.on('end', () => {
      try { const { text } = JSON.parse(raw);
        if (typeof text !== 'string' || !text) return send(422, { error: 'text missing' });
        const todo = { id: todos.length + 1, text, done: false }; todos.push(todo); send(201, todo);
      } catch { send(400, { error: 'invalid JSON' }); }
    }); return;
  }
  send(404, { error: 'not found' });
}).listen(3999, '127.0.0.1');

And this is how it answered on our server (we ran it with German messages; translated here):

$ curl localhost:3999/todos
[{"id":1,"text":"Write article","done":false}]              [200]

$ curl -X POST localhost:3999/todos -d '{"text":"Coffee"}'
{"id":2,"text":"Coffee","done":false}                       [201]

$ curl -X POST localhost:3999/todos -d '{"text":}'
{"error":"invalid JSON"}                                    [400]

$ curl -X POST localhost:3999/todos -d '{}'
{"error":"text missing"}                                    [422]

$ curl localhost:3999/nothing
{"error":"not found"}                                       [404]

Five calls, five different status codes, each telling the caller exactly what’s going on. That’s the real work in building an API: not the happy path, but the answers to everything that can go wrong. The difference between 400 and 422 looks pedantic, but it’s gold for the caller: 400 means their JSON has a syntax error, 422 means a field is missing. Two completely different bugs.

What this mini example lacks is exactly what makes a real API: the data is gone after a restart (no database — our SQLite vs PostgreSQL comparison fits here), anyone can write (no authentication), and nobody slows down a caller sending 10,000 requests a second (no rate limit). The next sections cover those three.

Jay Mayor, March 2026: a calm beginner walkthrough of how an API connects apps, if you prefer seeing it explained visually.

API keys, tokens and authentication

Most APIs want to know who’s asking. Not out of curiosity, but for three solid reasons: to bill you, to trace abuse back to a specific account, and to decide what you’re allowed to see.

API key: the simplest way

An API key is a long random string the provider gives you. You send it with every request, usually in a header:

curl -H "Authorization: Bearer YOUR_KEY" https://api.example.com/v1/data

We tried what happens with a wrong key at GitHub:

$ curl -H "Authorization: Bearer wrong" https://api.github.com/user
{ "message": "Bad credentials", "status": "401" }

And what happens if you try something that needs permissions without any key at all — say, deleting one of our own public repositories or opening an issue on it? Both times 401, not 403 and not 404. GitHub is saying: “I don’t know who you are, so I won’t even check whether you’re allowed.” Reading, on the other hand, works without a key: GET on the same repository returned 200 with 8,037 bytes of JSON.

The key is a password — treat it like one

This is where most things go wrong in practice. An API key is a password that doesn’t look like a password. Whoever has it is you to the API — including your bill. Typical ways keys get lost:

• In frontend code. Anything that runs in the browser can be read by every visitor. A key in a JavaScript file is public, however well hidden.
• In a Git repository. Once committed, the key lives in history, even if the next commit removes it.
• In a .env file the web server happens to serve. Real numbers from our log below.
• In screenshots and support tickets.

The rule: keys belong on the server, in environment variables or a secret store, with as few permissions as possible. And if one leaks: revoke it at the provider immediately, don’t just delete it from your code. A deleted key isn’t invalid — it’s just no longer with you.

OAuth: when you give someone else access

When an app offers “Sign in with Google” or a tool wants access to your GitHub account, it’s usually OAuth 2.0. The difference from an API key: you don’t give the app your password; the provider issues it a time-limited token with restricted permissions (“may read repositories, may not delete them”). You can revoke it at any time without changing your password. For your own scripts an API key is usually enough; OAuth matters once other people grant your app access to their accounts.

Rate limits: why an API says “stop”

Every serious public API limits how often you can ask. At GitHub you can see it right in the response headers:

x-ratelimit-limit: 60
x-ratelimit-remaining: 59
x-ratelimit-used: 1
x-ratelimit-reset: 1791792137

Unauthenticated: 60 requests per hour, counted per IP address. With our token it read "limit": 5000. The reset value is a Unix timestamp — the moment the quota refills. Exceed it and you don’t get a crash, you get a clean 403 or 429 with exactly these headers, and a well-built program then waits until the reset instead of blindly hammering on.

The trick that saves quota — and where it doesn’t work

Many APIs send an ETag with every response, a kind of fingerprint of the content. If you ask again with If-None-Match: <ETag> and nothing changed, the server answers 304 Not Modified with no body. That saves bandwidth — and, according to GitHub’s documentation, quota.

We measured it, and the result is more interesting than the docs:

Without authentication, each 304 still cost one request from the quota. With a token, it cost nothing. So at GitHub the saving trick only works for authenticated calls — if you poll anonymously, you burn your 60 requests even when nothing changed. That’s exactly the kind of detail no beginner tutorial mentions, and the reason a script dies at 3 a.m. with “rate limit exceeded”.

More headers that save you work

• Compression: the same GitHub response was 8,037 bytes uncompressed and only 1,638 bytes with Accept-Encoding: gzip — a fifth. Most HTTP libraries do this automatically; curl only when asked.
• Pagination: lists almost never arrive complete. GitHub puts the next step in the Link header: our request for our organization’s repositories with per_page=2 returned rel="next" (page 2) and rel="last" (page 6). Read only the first response and you’ll believe there are two repositories.
• CORS: whether an API may be called directly from a browser is decided by the Access-Control-Allow-Origin header. Open-Meteo, GitHub and Moltbook all returned * — anyone may. With APIs that don’t allow it, a browser call is blocked even though curl works. That isn’t a bug in the API; it’s a browser safety feature.

Which kinds of APIs exist

“API” is an umbrella term. Day to day you’ll mostly meet these:

Web APIs (REST)

What this article is mostly about: HTTP requests, JSON responses, endpoints as URLs. Most public services — payment providers, shipping carriers, weather services, AI models — offer REST APIs.

GraphQL

With GraphQL there’s only one endpoint, and the caller describes exactly which fields they want in a query language. Upside: no surplus data, no ten requests for ten related things. Downside: caching and rate limiting get harder because every request looks different. We’ll put it head-to-head against REST in a separate article.

Webhooks: the API turned around

With a normal API, you ask. With a webhook, the other service calls you as soon as something happens — for example, the payment provider hits your URL when a payment arrives. That saves you from asking every few seconds (“paid yet?”) and frees you from rate limits. In return you have to run an endpoint reachable from outside — and verify that the call really comes from the provider, usually via a signature header.

Library and system APIs

Not every API goes over the network. When a program opens a file, it calls the operating system’s API. When you write JSON.parse() in JavaScript, you’re using the language’s API. Same principle — a contract for how to call something and what comes back — just without HTTP in between.

Private, partner and public APIs

APIs are also distinguished by who may use them. Private APIs connect your own website to your own backend; partner APIs are given to selected business partners (a marketplace for its sellers, say); public APIs are open to anyone after signing up. Technically they’re often identical — the difference lies in documentation, contracts, and how long an old version must keep running.

What APIs are used for in everyday life

Nearly every app you use is, at its core, an interface in front of a few APIs:

• Weather apps ask a weather API, as shown above.
• Online stores talk via APIs to payment providers, carriers, inventory systems and marketplaces. A shop system like Shopware has a complete API of its own for managing products, orders and customers — the basis of every integration, see our Shopware installation guide.
• “Sign in with Google” is OAuth over Google’s API.
• AI tools are almost always API calls: the app sends your text to a model provider’s API and displays the answer. When a tool asks for your “API key”, it wants to bill your account at that provider. More in ChatGPT vs Claude vs Gemini and, for AI agents that call APIs on their own, our overview of AI agents for business.
• Automation with tools like Zapier, n8n or a plain cron job is nothing more than “call API A, take the result, send it to API B”. How such a recurring call runs on your own server is covered in Create a cron job.

Why bots keep looking for APIs that don’t exist

Now the part you won’t find in any introduction. getmind.io is a static website: HTML files, images, nothing else. There is not a single API here. We counted anyway, in our server logs.

Period September 7 to October 12, 2026, 197,887 requests in total. Of those, 10,179 went to paths like /api/…, /graphql, /v1/graphql or /wp-json — from 525 different IP addresses. Result: 9,964 times 404, 215 times a redirect, not one hit. The most common targets:

And right next to them, not API but the same motive: 578 hits on /.env, 395 on /.env.local, 316 on /.env.production. Those are the files where many projects keep their API keys. The scanners aren’t looking for the API itself — they’re looking for the keys to other people’s APIs: payment services, cloud accounts, AI providers.

Three very practical rules follow if you run an API yourself:

1. Assume it will be found. An endpoint “nobody knows about” gets probed by automated scanners within days. Obscurity isn’t protection.
2. Config files don’t belong in the web root. If /.env on your server returns 200 instead of 404, your keys are public.
3. Answer unknown requests tersely. A bare 404 reveals nothing. An error page with framework version, stack trace and database name reveals everything. How to lock out such regular visitors on top is covered in Fail2ban setup and IT security vulnerabilities.

By the way, anyone putting their own API online almost always puts it behind a reverse proxy, which handles HTTPS, compression and first filters before a request reaches the actual program.

How to recognize a good API

When you have to pick an API — for a store, a script, a project — these are the points we check before writing a single line of code:

• Documentation with real examples, including the error cases. Docs that only show the happy path hide half the story.
• Versioning in the URL or a header (/v1/, /v2/). Without a version, the provider can pull the response structure out from under you at any time.
• Meaningful status codes. An API that returns 200 OK with {"error": true} in the body makes every bit of error handling painful.
• Documented rate limits — and headers that reveal the current state.
• A test environment (sandbox), especially for anything that moves money.
• A status page and a changelog. When you need to know at night whether the error is yours or the provider’s, that’s the first stop.
• A way to create keys with restricted permissions. A script that only reads orders doesn’t need a key that can delete products.

Frequently asked questions about APIs

What is an API in simple terms?

An API is a defined interface through which one program can ask another for data or an action. Think of it as a menu plus a waiter: you can only order what’s on the menu, you get it back in a fixed form, and you don’t need to know how the kitchen behind it works. On the web this usually happens over HTTP with JSON responses.

What does API stand for?

API stands for Application Programming Interface. It’s an interface meant for programs, not people — as opposed to a user interface, which is made for humans.

What is the difference between an API and an interface?

“Interface” is the broader term and can also mean hardware, such as a USB port, or the screen a user interacts with. An API is specifically a software interface: a defined set of calls through which programs talk to each other.

What is an API key and how do I get one?

An API key is a long random string that identifies you to an API. You get it after signing up, in the provider’s developer or account area. It’s sent with every request, usually in the Authorization header, and must be kept secret like a password — whoever has it acts in your name and on your bill.

Are APIs free?

That’s up to the provider. Many APIs have a free tier: Open-Meteo answers simple requests without sign-up, GitHub allows 60 requests per hour anonymously and 5,000 with a token. AI models, payment processing or map APIs, on the other hand, usually charge per request or per amount of data processed.

What is the difference between a REST API and an API?

“API” is the umbrella term for any programming interface. A REST API is one particular style of web API that uses HTTP methods (GET, POST, PUT, DELETE), resources as URLs and usually JSON. Other styles include GraphQL, gRPC and older SOAP interfaces.

Do I need to know how to code to use an API?

Not for a first call: many GET requests can be opened directly in the browser, and with curl one line in the terminal is enough. Automation tools like Zapier or n8n make API calls with a few clicks. Once you want to process data, handle errors or poll regularly, basic knowledge of a language like Python or JavaScript helps a lot.

What does a 401 error from an API mean?

401 means the API doesn’t know who you are: the key is missing, mistyped, expired or in the wrong header. GitHub’s message for this is “Bad credentials”. By contrast, 403 means you were recognized but lack permission for that action.

What does a 429 error mean?

429 Too Many Requests means you’ve exceeded the rate limit. The fix is to wait, not retry: often a Retry-After header or a ratelimit-reset field tells you when requests are allowed again. Good programs wait automatically with growing intervals (exponential backoff).

Are APIs secure?

An API is as secure as its protections. Typical weaknesses are missing authorization checks (user A can read user B’s order via /orders/124), leaked keys, missing rate limits and overly detailed error messages. Our own log recorded over 10,000 automated requests to API paths in five weeks — an API on the internet will be found, whether it’s linked or not.

What is the difference between an API and a webhook?

With an API you actively ask (“Any new orders?”). With a webhook the other service contacts you on its own as soon as something happens (“Here’s a new order”). Webhooks spare you constant polling but require you to run an endpoint reachable from outside and to verify where the message came from.

Conclusion

At its core an API is nothing mysterious: a contract between two programs, usually an HTTP request with a JSON response. You can write your first call in one line, and a working API of your own fits in 16.

The effort lies elsewhere — and our measurements show fairly precisely where. An third-party call is roughly fifty times slower than a local one, and ignoring that in a loop means waiting minutes instead of seconds. A saving trick the documentation promises only works at GitHub when you’re authenticated; anonymously, even the “nothing changed” answer costs quota. A list whose first page shows two entries actually has six pages. And a website with no API at all still receives hundreds of requests to /api/ and /.env every day, because somebody out there hopes you left your keys lying around.

Using an API is easy. Using it well means reading the error cases, not just the examples.

If you want to keep going: What is a JSON file explains the format almost every API answers in, What is a reverse proxy shows how to put your own API online properly, and What is Docker explains how to package it so it runs the same everywhere. If you’re setting up a server for it right now, start with Linux server setup.