What Is a REST API: How It Works Explained With Real Examples

/ Uncategorized

If you have been building software for even a short while, you have probably heard the phrase REST API dropped into conversations, job descriptions, and documentation. You may have used one without ever getting a clean, practical explanation of what it actually is. This guide fixes that. We will break down what a REST API is, why it matters, how it works under the hood, and we will look at real code so you can see it in action.

What Is a REST API?

A REST API (Representational State Transfer Application Programming Interface) is a way for two applications to communicate over HTTP by exchanging representations of resources, usually in JSON format. In simpler words: it is a set of rules that lets a client (like a browser, a mobile app, or another server) ask a server for data or tell it to change data, using standard web requests.

REST is not a protocol or a tool. It is an architectural style proposed by Roy Fielding in his 2000 doctoral dissertation. When an API follows the REST principles, we call it RESTful.

rest api code screen

Why REST APIs Became the Standard

REST APIs dominate the web because they are:

  • Simple: they rely on HTTP, which every developer already knows.
  • Language-agnostic: any client that can send an HTTP request can consume them.
  • Scalable: statelessness makes them easy to distribute across servers.
  • Readable: JSON payloads are easy for humans and machines to parse.

The Core Principles of REST

An API is considered RESTful when it respects these six constraints:

1. Client-Server Architecture

The client and the server are independent. The client handles the user interface, the server handles data storage and business logic. They can evolve separately as long as the contract (the API) stays stable.

2. Statelessness

Every request from the client to the server must contain all the information the server needs to understand and process it. The server does not store anything about the client session between requests. If you need to be authenticated, you send your token with every request.

3. Cacheability

Responses must declare whether they can be cached. Good caching improves performance and reduces load on the server.

4. Layered System

The client does not need to know if it is talking directly to the server or going through a load balancer, a proxy, or a gateway. Each layer only knows about the next one.

5. Uniform Interface

This is the heart of REST. Resources are identified by URLs, actions are expressed with HTTP verbs, and representations (JSON, XML) describe the state of a resource.

6. Code on Demand (Optional)

The server can send executable code to the client, but this constraint is rarely used in practice. There’s a good explainer over at geeksforgeeks.org.

Resources and Endpoints Explained

In REST, everything is a resource: a user, an order, a product, a comment. Each resource is identified by a URL called an endpoint.

Examples:

  • /users represents the collection of users
  • /users/42 represents the user with ID 42
  • /users/42/orders represents the orders belonging to user 42

Notice how the URLs are nouns, not verbs. The action is expressed by the HTTP method, not the URL.

rest api code screen

The HTTP Verbs You Need to Know

Verb Purpose Example Idempotent?
GET Retrieve data GET /products Yes
POST Create a new resource POST /products No
PUT Replace a resource PUT /products/10 Yes
PATCH Partially update a resource PATCH /products/10 No
DELETE Remove a resource DELETE /products/10 Yes

HTTP Status Codes You Will See Often

  • 200 OK: request succeeded
  • 201 Created: resource was created successfully
  • 204 No Content: success with no body to return
  • 400 Bad Request: the client sent invalid data
  • 401 Unauthorized: authentication is missing or wrong
  • 403 Forbidden: authenticated but not allowed
  • 404 Not Found: the resource does not exist
  • 500 Internal Server Error: something broke on the server

How a REST Request and Response Actually Look

Let’s say we want to fetch a product with ID 10 from an online store. Source: https://redhat.com.

The Request

GET /api/products/10 HTTP/1.1
Host: api.mystore.com
Authorization: Bearer abc123token
Accept: application/json

The Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 10,
  "name": "Wireless Headphones",
  "price": 79.99,
  "stock": 42,
  "category": "audio"
}

That’s it. That’s the whole magic. A URL, a verb, some headers, and a JSON payload coming back.

rest api code screen

Real Code Examples

Consuming a REST API with JavaScript (fetch)

// GET request
const response = await fetch('https://api.mystore.com/api/products/10', {
  headers: {
    'Authorization': 'Bearer abc123token',
    'Accept': 'application/json'
  }
});
const product = await response.json();
console.log(product);

// POST request to create a new product
const newProduct = await fetch('https://api.mystore.com/api/products', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer abc123token'
  },
  body: JSON.stringify({
    name: 'Bluetooth Speaker',
    price: 49.99,
    category: 'audio'
  })
});
console.log(await newProduct.json());

Consuming a REST API with Python (requests)

import requests

headers = {
    'Authorization': 'Bearer abc123token',
    'Accept': 'application/json'
}

# GET
r = requests.get('https://api.mystore.com/api/products/10', headers=headers)
print(r.status_code, r.json())

# DELETE
r = requests.delete('https://api.mystore.com/api/products/10', headers=headers)
print(r.status_code)

Building a Tiny REST API with Node.js and Express

import express from 'express';
const app = express();
app.use(express.json());

let products = [
  { id: 1, name: 'Mug', price: 9.99 },
  { id: 2, name: 'T-shirt', price: 19.99 }
];

app.get('/api/products', (req, res) => res.json(products));

app.get('/api/products/:id', (req, res) => {
  const product = products.find(p => p.id === Number(req.params.id));
  if (!product) return res.status(404).json({ error: 'Not found' });
  res.json(product);
});

app.post('/api/products', (req, res) => {
  const product = { id: Date.now(), ...req.body };
  products.push(product);
  res.status(201).json(product);
});

app.listen(3000, () => console.log('API running on port 3000'));

REST API vs Regular API: What’s the Difference?

An API is any interface that allows two pieces of software to talk to each other. It could be a library, a SOAP service, a GraphQL endpoint, or a REST endpoint. A REST API is a specific type of API that follows the REST architectural constraints and uses HTTP. All REST APIs are APIs, but not all APIs are REST APIs.

Common Mistakes Beginners Make

  1. Using verbs in URLs: writing /getUser/5 instead of /users/5.
  2. Ignoring status codes: returning 200 OK with an error message inside the body.
  3. Making the API stateful: storing session data on the server between calls.
  4. Inconsistent naming: mixing /users, /User, and /customers for the same concept.
  5. No versioning: shipping breaking changes without a /v2/ prefix or a version header.
rest api code screen

Best Practices for Designing a Clean REST API

  • Use plural nouns for collections (/orders, not /order).
  • Keep URLs lowercase and use hyphens for readability.
  • Return meaningful HTTP status codes.
  • Version your API from day one (/api/v1/...).
  • Document everything with OpenAPI or Swagger.
  • Secure endpoints with HTTPS and token-based authentication.
  • Support filtering, sorting, and pagination on list endpoints (?page=2&sort=price).

Tools That Make Working With REST APIs Easier

  • Postman or Insomnia: test and explore APIs without writing code.
  • cURL: the command-line classic for quick requests.
  • Swagger UI: interactive documentation for your endpoints.
  • Bruno: an open-source, offline-first alternative to Postman.

Frequently Asked Questions

What are the 4 main methods of a REST API?

The four most used HTTP methods in REST are GET (read), POST (create), PUT or PATCH (update), and DELETE (remove). Together they cover the classic CRUD operations.

Is REST API hard to learn?

No. If you understand HTTP basics and JSON, you can start consuming REST APIs within an hour. Designing a well-structured REST API takes more practice, but the core concepts are approachable for any developer.

Is Postman a REST API?

No. Postman is a client tool used to send requests to REST APIs (and other types of APIs). It helps you test, debug, and document APIs, but it is not an API itself. See restfulapi.net for their take.

What is the difference between REST and RESTful?

REST is the architectural style. RESTful is an adjective describing an API that follows REST principles. In everyday conversation, the two terms are used interchangeably.

What format do REST APIs use?

Most modern REST APIs exchange data in JSON because it is lightweight and easy to parse. XML, YAML, or even plain text are also possible, though far less common today.

Does REST require HTTPS?

REST itself does not, but in production you should always use HTTPS to encrypt traffic, protect tokens, and keep user data safe.

Wrapping Up

A REST API is nothing more than a well-organized way to expose data and actions over HTTP, using URLs as resources and verbs as actions. Once you internalize the ideas of statelessness, resources, and the uniform interface, every REST API you meet starts to feel familiar. Pick a public API, fire up Postman or cURL, and start making requests. That’s the fastest way to turn theory into intuition.