What Is an API? A Plain-English Explanation

An API is a set of requests one program agrees to answer for another.

That is genuinely it. A weather service does not let your code rummage through its database — it publishes a list of questions it will answer, in a fixed format, and your program asks one.

A real example#

You want today’s exchange rate. You do not get access to the bank’s systems. Instead you send a request to a published address:

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

And you get back a block of JSON:

{
  "base": "GBP",
  "date": "2026-09-06",
  "rates": {
    "USD": 1.27,
    "EUR": 1.17
  }
}

Your code reads what it needs and ignores the rest. Neither side knows anything about how the other is built — that separation is the entire point.

The four parts of a request#

1. The endpoint#

A URL representing one kind of thing. Most APIs organise them by noun:

/users            all users
/users/42         one specific user
/users/42/orders  that user's orders

2. The method#

What you want done to it.

Typing a URL into your address bar is always a GET, which is why you can test read-only endpoints by just visiting them.

3. The data you send#

Small values go in the URL as a query string: ?base=GBP&limit=10. Anything larger goes in the request body as JSON, usually with POST.

4. The headers#

Information about the request rather than the request itself — most often your identity and the format you are sending:

const response = await fetch("https://api.example.com/notes", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_TOKEN",
  },
  body: JSON.stringify({ title: "Hello", body: "First note" }),
});

What comes back: status codes#

Every response carries a number saying how it went. Learn the ranges rather than the individual codes.

The 4xx/5xx split is the useful one: 4xx means fix your request, 5xx means wait and try again.

Reading the documentation#

API docs are long and you never read them front to back. Find these four things:

1. The base URL. Everything hangs off it.
2. Authentication. Key in a header? In the query string? None needed?
3. The one endpoint you want, and its required parameters.
4. An example response. This tells you the field names, which is what your code actually depends on.

Then make one real request before writing any code — paste the URL into your browser, or use the DevTools Network tab. Reading the real response beats trusting the documented one, because docs go stale.

const raw = await response.json();
console.log(JSON.stringify(raw, null, 2));   // look at what actually arrived

API keys, and why yours is public#

Most APIs identify you with a key. It goes in a header or the query string.

Anything in front-end JavaScript is visible to anyone who opens DevTools. Not obscured, not hard to find — visible in the Network tab on the first request. Minifying does not help, and neither does storing it in a variable with a boring name.

What that means in practice:

• Learning project, free tier, read-only data? Acceptable. Know that the key is exposed and use one you can revoke.
• Anything that costs money, writes data, or touches an account? The key belongs on a server you control. Your page calls your server; your server holds the key and calls the API.

See back-end development for what that server looks like.

Rate limits#

APIs cap how often you may call them — say 60 requests a minute. Go over and you get 429 Too Many Requests.

Two habits that keep you well under:

• Do not call on every keystroke. Wait until the user pauses typing, or until they leave the field.
• Cache what does not change. Exchange rates for today do not need re-fetching every render.

The CORS error#

Sooner or later:

Access to fetch at 'https://api.example.com' from origin
'http://localhost:5500' has been blocked by CORS policy

This is a browser security rule, not a bug in your code. A site can only read a response from another domain if that domain explicitly permits it.

You cannot fix it in your JavaScript. Your options are to use an API that allows browser requests, or to make the call from your own server, which is not subject to the rule.

Other meanings of “API”#

The word is broader than web services. A library’s API is the set of functions it exposes; the DOM API is what the browser gives your JavaScript. Same idea each time — a published surface one piece of code offers another — but on the web, “API” almost always means the HTTP kind described here.

Where to go next#

• JavaScript Fetch API explained
• Async and await explained
• Web development for beginners