REST APIs explained with a restaurant (and one real request you can run)

If you have ever been told "just call the API" and nodded without knowing what that meant, this post is for you. No jargon, one analogy, and one real request at the end.

The restaurant analogy

Think of a restaurant.

• You are the app that wants something.
• The kitchen is the server that has the data.
• The waiter is the API.

You do not walk into the kitchen. You tell the waiter what you want, in a format the waiter understands, and the waiter brings back the dish. An API is that waiter: a fixed way for one program to ask another program for something.

REST is a popular set of rules for how that waiter behaves. REST APIs talk over the web (HTTP), so the "order" is just a web request and the "dish" is usually JSON.

What a request is made of

Every request has four parts:

1. A URL says what you are asking for, like https://api.example.com/users/42.
2. A method says what you want to do. The four you will meet most: GET (read), POST (create), PUT or PATCH (update), DELETE (remove).
3. Headers carry extra info, like your API key, which proves who you are.
4. A body (only for POST, PUT and PATCH) carries the data you are sending.

The reply has a status code (200 means fine, 404 means not found, 401 means your key is missing or wrong, 429 means you asked too often) and a body, usually JSON.

What JSON looks like

JSON is just labelled values:

{
  "amount": 100,
  "from": "USD",
  "to": "INR"
}

Curly braces hold a thing, each label sits in quotes, and a colon connects it to its value. If you can read a form, you can read JSON.

Send a real request

Here is a currency conversion call. You need a free API key from the Currency Exchange Rates API on APIHiver, which is a marketplace where you can try APIs in the browser first.

curl "https://currency-exchange-rates.p.apihiver.com/v1/convert?amount=100&from=USD&to=INR" \
  -H "X-API-Key: YOUR_API_KEY"

Reading it piece by piece:

• curl sends the request from your terminal.
• The URL says convert and passes three options after the ?: how much, from which currency, to which currency.
• -H "X-API-Key: ..." is the header with your key.

The reply is JSON with the converted amount. That is a complete REST API call: URL, method (GET is the default), header, JSON back.

The same call in JavaScript

const res = await fetch(
  "https://currency-exchange-rates.p.apihiver.com/v1/convert?amount=100&from=USD&to=INR",
  { headers: { "X-API-Key": process.env.API_KEY } }
);
const data = await res.json();
console.log(data);

Note the key comes from an environment variable. Never paste a key into front-end code or a public repo. Anyone can read it there and run up your bill.

Three mistakes beginners make

• Hard-coding keys. Use environment variables and keep them server-side.
• Ignoring the status code. Check res.ok before you trust the body.
• Calling the API on every page view. Cache results that rarely change. It is faster and saves your quota.

Where to go next

I wrote a longer version of this guide with REST vs SOAP vs GraphQL, a status code table and a short quiz: What Is a REST API? A Beginner's Guide.

If you have a question about a part that still feels fuzzy, ask in the comments and I will answer it.