What Is a REST API? Simple Explanation With Examples (2026)

You have probably heard developers say things like "just call the REST API." If that sounds like another language, this guide is for you.

By the end of this page you will know what a REST API is, how it works, and how to use one yourself, with no coding background needed. We will use everyday examples, and at the end you will make a real API request and read the answer.

First, what is an API?#

API stands for Application Programming Interface. That is a mouthful, so here is the idea in one line:

An API is a set of rules that lets one piece of software talk to another.

You use APIs every day without noticing:

• Your phone's weather app does not measure the weather itself. It asks a weather service for the forecast through an API.
• When you pay with UPI or a card on a shopping site, the site talks to a payment service through an API.
• When a website says "Sign in with Google", it asks Google through an API whether you really are you.
• A travel site that shows hotels from many providers is pulling them in through APIs.

So an API is the messenger. It carries your request to another system and carries the answer back.

The restaurant analogy#

Imagine you sit down at a restaurant.

• You are the app (the client). You are hungry for data.
• The kitchen is the server. It has all the food, which here means the data.
• You cannot just walk into the kitchen and grab things. That would be chaos and unsafe.
• So there is a waiter. You tell the waiter what you want from the menu. The waiter takes your order to the kitchen and brings back your meal.

The waiter is the API. The menu is the API documentation, the list of what you are allowed to order and how to ask. You do not need to know how the kitchen works. You only need to know how to order.

A REST API is a particular, very popular way of designing that waiter so that ordering is simple and predictable.

So what does REST mean?#

REST stands for Representational State Transfer. Do not worry about memorising that. Roy Fielding, a computer scientist, described the idea in his doctoral thesis in the year 2000.

In plain English, REST is a set of habits for building web APIs:

1. Everything is a "thing" with an address. A customer, a product, a hotel, a currency rate: each one is a resource, and each has a web address (URL).
2. You use the same few verbs for everything. Instead of inventing new commands, you use the standard web verbs like GET (read) and POST (create).
3. Each request stands alone. The server does not need to remember your previous request. You include everything it needs every time.
4. The answer comes back in a common format, almost always JSON.

Because these habits are so simple and standard, developers can learn one REST API and quickly understand the next one. That is why most web APIs you meet are REST APIs.

"REST API vs API": what is the difference?#

This is one of the most searched questions, and the answer is short:

• API is the big category. It means any rules that let two programs talk.
• REST API is one style of web API.

Think of "vehicle" and "car". Every car is a vehicle, but not every vehicle is a car. In the same way, every REST API is an API, but some APIs (such as SOAP or GraphQL ones) are not REST.

The 4 parts of every API request#

When your app calls a REST API, it sends a request made of four parts. Once you know these, you can read almost any API's documentation.

1. The URL (where to send it)#

The URL is the address of the thing you want. For example:

https://currency-exchange-rates.p.apihiver.com/v1/convert

You can read it like a sentence: "On the currency service, use version 1, and do a convert." Extra details go at the end after a question mark. These are called query parameters:

...v1/convert?amount=100&from=USD&to=INR

That means: "convert an amount of 100 from USD to INR."

2. The method (what you want to do)#

The method is the verb. It tells the server what kind of action you want. Here are the five you will see most often, with an everyday comparison:

If you are only fetching information, you will use GET almost every time.

3. The headers (extra information about the request)#

Headers are small notes attached to the request. The most important one for beginners is the API key, which works like your membership card. It tells the service who you are, so it knows you are allowed to use it and how many requests you have left on your plan.

X-API-Key: YOUR_API_KEY

4. The body (the data you send)#

For GET requests there is usually no body. For POST, PUT and PATCH, the body carries the data you are sending, like the details of a new customer. It is normally written in JSON, which we explain next.

What comes back: the response#

After you send the request, the server replies with two things.

The status code (how it went)#

This is a three-digit number that says whether your request worked. You do not need to memorise them all. Learn these:

A handy rule: codes starting with 2 mean success, 4 means you made a mistake, and 5 means the server had a problem.

The data (usually JSON)#

The actual answer usually comes back as JSON (pronounced "Jason"). It looks like this:

{
  "from": "USD",
  "to": "INR",
  "amount": 100,
  "rate": 95.82,
  "result": 9582
}

JSON is just labelled information. Each line has a name on the left and a value on the right, like a form that has been filled in. Even if you have never coded, you can read it: convert 100 USD into INR at a rate of 95.82, and the result is 9,582.

Try a real REST API yourself#

Reading is good, but doing it makes it click. Let us call a real API. We will use the Currency Exchange Rates API on APIHiver, which returns daily rates published by the European Central Bank.

Step 1: get a free API key#

1. Create a free APIHiver account.
2. Open the Currency Exchange Rates API.
3. Subscribe to a free plan.
4. Copy your key from your dashboard.

Step 2: send the request#

This is the request in cURL, a tool that sends requests from a terminal. Put your own key where it says YOUR_API_KEY.

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

Read it piece by piece:

• curl is the tool that sends the request.
• The URL is the where and the what: convert 100 US dollars into Indian rupees.
• -H "X-API-Key: ..." is the header, your membership card.
• There is no method written, because GET is the default.

Step 3: read the answer#

You get back something like this (the exact rate changes daily):

{
  "to": "INR",
  "date": "2026-09-25",
  "from": "USD",
  "rate": 95.82,
  "amount": 100,
  "result": 9582
}

You just used a REST API. You sent a GET request to a URL, with a header for your key, and got JSON back with a 200 status.

What if you forget a required value?#

Leave out the amount and the API replies with a 400 error and a helpful message:

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "amount: Field required"
  }
}

That is the waiter telling you: "Sorry, you forgot to say how many." A good API explains the mistake so you can fix it.

And if you leave out the key entirely, the service answers 401, the "who are you?" response.

The same call in JavaScript#

When you build a website or app, you make the call from code instead of a terminal. Here is the same request 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": "YOUR_API_KEY" } }
);
 
const data = await res.json();
console.log(`100 USD = ${data.result} INR`);

The same call in Python#

import requests
 
res = requests.get(
    "https://currency-exchange-rates.p.apihiver.com/v1/convert",
    params={"amount": 100, "from": "USD", "to": "INR"},
    headers={"X-API-Key": "YOUR_API_KEY"},
    timeout=10,
)
data = res.json()
print(f"100 USD = {data['result']} INR")

Notice that the idea is identical in every language: a URL, a method, a header, and a JSON answer. Only the spelling changes.

The rules that make an API "RESTful"#

Developers describe a good REST API as RESTful. Here are the main rules in plain language:

• Client and server are separate. The app (client) and the data store (server) can change independently, as long as the menu stays the same.
• Stateless. Every request carries all the information needed. The server does not remember your last visit, like a waiter who treats each order as brand new.
• Uniform and predictable. Resources have clear addresses and use the standard verbs, so once you learn one API, the next is familiar.
• Cacheable. Answers can be saved and reused for a short time. If a rate does not change until tomorrow, you do not need to ask a thousand times.
• Layered. Between you and the data there can be helpers, such as a gateway that checks your key and counts your requests, and you do not need to care.

REST vs SOAP vs GraphQL#

REST is not the only style. Here is how the three popular ones compare:

If you are starting out, learn REST first. It covers the vast majority of APIs you will meet, and everything you learn carries over to the others.

REST APIs you already know#

Big services you use offer REST APIs, which is a good way to see them in the wild:

• GitHub has a REST API (and a GraphQL one) that lets programs read repositories and issues.
• WordPress sites expose a REST API so apps can read posts and pages.
• Payment, maps, weather and travel companies publish REST APIs so other businesses can build on them.

On APIHiver you can browse dozens of REST APIs, from weather and currency rates to email validation and Indian IFSC and GSTIN lookups, and try them in a playground without writing any code.

Common beginner mistakes (and how to avoid them)#

1. Forgetting the API key. You will get a 401. Add the header.
2. Using the wrong method. Trying to POST to a URL that expects GET gives an error. Check the docs.
3. Wrong value format. Dates are usually YYYY-MM-DD, and currency codes are usually three capital letters like USD. Match the examples.
4. Hitting the rate limit. If you send too many requests too fast you get a 429. Slow down and save answers you reuse.
5. Not reading the error message. Good APIs tell you exactly what went wrong. Read it before you search the web.
6. Putting secrets in front-end code. Anything in browser code can be seen by visitors. Call the API from your server instead.

Tips for using REST APIs well#

• Start with the documentation. It is the menu. Look at the example request and response first.
• Test before you code. Use a playground, Postman or cURL to see real answers.
• Check the status code first. Only read the data if the code starts with 2.
• Set a timeout. Do not let your app wait forever if the server is slow.
• Cache what does not change. It saves requests and money.
• Start on a free plan. Prove your idea works, then upgrade when you have users.

A quick quiz to check yourself#

Try to answer before reading the answer.

1. Which method would you use to read a list of products? GET.
2. What does a 404 mean? The thing you asked for was not found.
3. What format does the data usually come back in? JSON.
4. Whose fault is a 500 error? The server's, not yours.
5. What is the API key for? Telling the service who you are.

If you got four or five right, you understand REST APIs better than most beginners.

What to learn next#

Now that you know the basics, here is a sensible path:

1. Try three or four different APIs to see how similar they feel.
2. Learn to read documentation and find the parameters you need.
3. Build one tiny project, such as a currency converter or a weather widget.
4. Learn authentication beyond API keys, such as OAuth, once you need it.

If you are into travel or hotel data, these guides show REST APIs in action:

• Best Travel APIs for Developers in 2026
• Booking.com API: How to Get a Free API Key
• Hotel API & Hotel Booking API: 6 Options Compared
• How to Validate an Email Address in Your App

Summary#

• An API lets two programs talk. A REST API is the most popular style of web API.
• A request has four parts: a URL, a method, headers and sometimes a body.
• A response has a status code and usually JSON data.
• Learn the verbs (GET, POST, PUT, PATCH, DELETE) and the main status codes (200, 400, 401, 404, 429, 500) and you can read almost any API.
• The best way to learn is to make a real request, and you just did.