What Is a REST API?

If you have ever used a weather app, logged in with Google, or made an online payment, you have interacted with a REST API — you just did not see it. REST APIs are the invisible backbone of modern software, enabling applications to communicate with each other over the internet. Understanding REST APIs is essential knowledge for every developer, whether you are building frontends, backends, mobile apps, or integrating third-party services.

This guide explains what REST APIs are from the ground up — no prior API knowledge required. By the end, you will understand how APIs work, how to read and write API requests, and how to design your own RESTful services.

What Is an API?

An API (Application Programming Interface) is a set of rules that allows one piece of software to talk to another. It defines what requests you can make, what data you need to send, and what response you will get back.

Real-world analogy: Think of a restaurant. You (the client) do not go into the kitchen to cook your food. Instead, you tell the waiter (the API) what you want from the menu (the request). The waiter takes your order to the kitchen (the server), and brings back your food (the response). The API is the waiter — the middleman that lets you interact with the kitchen without knowing how the food is actually prepared.

In software: your mobile app (client) does not directly access the database. Instead, it sends a request to the API, which talks to the database and returns the data in a structured format.

What Is a REST API?

REST stands for Representational State Transfer. It is an architectural style (a set of design principles) for building web APIs. A REST API is an API that follows these REST principles — using standard HTTP methods, resource-based URLs, and stateless communication.

REST was defined by Roy Fielding in his 2000 doctoral dissertation. It became the dominant web API architecture because it leverages the existing HTTP protocol that powers the web — no special software, protocols, or libraries needed. Any device that can make HTTP requests can use a REST API.

A REST API exposes "resources" (data entities like users, products, orders) at specific URLs, and you interact with them using standard HTTP methods (GET to read, POST to create, PUT to update, DELETE to remove).

How REST APIs Work

Every REST API interaction follows this pattern:

// Request
GET https://api.example.com/users/123
Headers: { "Authorization": "Bearer eyJhbG..." }

// Response (200 OK)
{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "role": "admin",
  "createdAt": "2024-01-15T10:30:00Z"
}

HTTP Methods in REST APIs

REST APIs use HTTP methods (also called verbs) to indicate what action to perform on a resource. Each method has a specific purpose:

GET /users/123

POST /users
Body: { "name": "Bob", "email": "bob@example.com" }

PUT /users/123
Body: { "name": "Alice Smith", "email": "alice@new.com" }

PATCH /users/123
Body: { "name": "Alice Smith" }

DELETE /users/123

HTTP Status Codes

Status codes tell the client what happened with their request:

The 6 REST Constraints

For an API to be truly "RESTful," it must follow these architectural constraints:

REST API URL Design Best Practices

Well-designed URLs make your API intuitive and self-documenting. REST URLs should represent resources (things), not actions:

GET /users
GET /users/123
POST /users
PUT /users/123
DELETE /users/123
GET /users/123/orders
GET /products?category=electronics
GET /api/v2/users

GET /getUsers
POST /createUser
POST /deleteUser/123
GET /fetchAllProducts
POST /api/v1/updateUserEmail
GET /getAllOrdersForUser

• Use nouns, not verbs: The HTTP method is the verb. The URL is the noun (resource).
• Use plural names: /users (not /user), /products (not /product).
• Use lowercase and hyphens: /user-profiles (not /UserProfiles or /user_profiles).
• Version your API: /api/v1/users — allows backward-compatible changes.
• Nest for relationships: /users/123/orders — orders belonging to user 123.

REST API Request Structure

Every REST API request consists of several components. Understanding each part helps you read API documentation and debug issues effectively:

POST https://api.example.com/v1/users?notify=true
Headers:
  Content-Type: application/json
  Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
  Accept: application/json
Body:
  {
    "name": "Alice",
    "email": "alice@example.com",
    "role": "editor"
  }

REST API Authentication Methods

Most APIs require authentication to identify who is making the request and what permissions they have. Here are the four most common authentication methods used with REST APIs:

GET /api/weather?city=London&apiKey=abc123def456

GET /api/profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

GET /api/user/repos
Authorization: Bearer github_pat_abc123... (OAuth access token)

GET /api/dashboard
Cookie: session_id=abc123def456 (sent automatically by browser)

For most modern applications: use JWT for APIs consumed by mobile/SPA clients, OAuth 2.0 for third-party integrations, and API keys for simple server-to-server communication. See ourJWT vs Session Authenticationguide for a deeper comparison.

REST vs SOAP vs GraphQL

Building a Simple REST API (Node.js + Express)

Here is a complete, working REST API for a "users" resource in under 50 lines:

const express = require("express")
const app = express()
app.use(express.json())

// In-memory "database"
let users = [
  { id: 1, name: "Alice", email: "alice@example.com" },
  { id: 2, name: "Bob", email: "bob@example.com" },
]

// GET all users
app.get("/api/users", (req, res) => {
  res.json(users)
})

// GET single user
app.get("/api/users/:id", (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id))
  if (!user) return res.status(404).json({ error: "User not found" })
  res.json(user)
})

// CREATE user
app.post("/api/users", (req, res) => {
  const { name, email } = req.body
  if (!name || !email) return res.status(400).json({ error: "Name and email required" })
  const user = { id: users.length + 1, name, email }
  users.push(user)
  res.status(201).json(user)
})

// UPDATE user
app.put("/api/users/:id", (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id))
  if (!user) return res.status(404).json({ error: "User not found" })
  user.name = req.body.name || user.name
  user.email = req.body.email || user.email
  res.json(user)
})

// DELETE user
app.delete("/api/users/:id", (req, res) => {
  users = users.filter(u => u.id !== parseInt(req.params.id))
  res.status(204).send()
})

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

This demonstrates all five CRUD operations (Create, Read, Update, Delete) mapped to HTTP methods. In production, you would add authentication, input validation, error handling, and connect to a real database — but the URL and method patterns remain the same.

REST API Best Practices

Common REST API Mistakes

Real-World REST API Examples

These popular APIs follow REST principles and are great examples to learn from:

Frequently Asked Questions

Related Tools & Articles