REST API

Explanation

REST (Representational State Transfer) is an architectural style defined by Roy Fielding in 2000. A REST API exposes resources (users, posts, orders) via URLs, and clients interact with those resources using HTTP verbs: GET /users (list users), GET /users/42 (get user 42), POST /users (create a user), PUT /users/42 (replace user 42), PATCH /users/42 (update fields of user 42), DELETE /users/42 (delete user 42). The URL identifies the resource; the HTTP method describes the operation. REST's six constraints are: client-server (UI and data storage are separated), stateless (each request contains all information needed — no server-side session), cacheable (responses can be cached), uniform interface (consistent resource-based URLs and HTTP semantics), layered system (proxies and gateways are invisible to the client), and code-on-demand (optional: server can send executable code). The stateless constraint is important: the server doesn't remember previous requests. Each request must include authentication (Bearer token, API key) and any context needed. This makes REST APIs horizontally scalable — any server instance can handle any request because no state is stored server-side. "RESTful" is a spectrum, not a binary. Many APIs called "REST APIs" violate REST principles: using GET for mutations, encoding the action in the URL (POST /deleteUser instead of DELETE /users/42), or returning 200 OK for errors. Truly RESTful APIs use HTTP semantics correctly and are self-descriptive.

Code Example

// RESTful API design: resource-based URLs + HTTP verbs

// Express.js RESTful router for a Posts resource
const express = require('express');
const router = express.Router();

// GET /posts          — list all posts
router.get('/', async (req, res) => {
  const posts = await Post.findAll({ where: buildFilters(req.query) });
  res.json(posts);  // 200 OK
});

// GET /posts/:id      — get one post
router.get('/:id', async (req, res) => {
  const post = await Post.findByPk(req.params.id);
  if (!post) return res.status(404).json({ error: 'Post not found' });
  res.json(post);   // 200 OK
});

// POST /posts         — create a post
router.post('/', authenticate, async (req, res) => {
  const post = await Post.create({ ...req.body, userId: req.user.id });
  res.status(201).json(post);  // 201 Created
});

// PATCH /posts/:id    — partial update
router.patch('/:id', authenticate, async (req, res) => {
  const [updated] = await Post.update(req.body, { where: { id: req.params.id }});
  if (!updated) return res.status(404).json({ error: 'Not found' });
  res.json(await Post.findByPk(req.params.id));  // 200 OK
});

// DELETE /posts/:id   — delete
router.delete('/:id', authenticate, async (req, res) => {
  await Post.destroy({ where: { id: req.params.id } });
  res.status(204).send();  // 204 No Content
});

Why It Matters for Engineers

REST APIs are the primary interface between frontend and backend in modern web and mobile applications. Knowing REST conventions means you can read and write API documentation correctly, design APIs that other developers can use intuitively, and debug API failures by interpreting status codes and response bodies. When you see a 422 vs 400, or a 204 vs 200, you know what they mean. REST also clarifies common AI-generated API bugs: AI often generates POST /getUsers (wrong — use GET /users), or returns 200 with {success: false} in the body (wrong — use a 4xx status code). Recognizing these violations and knowing the correct pattern is practical API engineering knowledge.