REST

Overview

REST (Representational State Transfer) is an architectural style for APIs built on HTTP. Everything is a resource identified by a URL (/users/42/orders), clients manipulate resources with standard methods (GET, POST, PUT, PATCH, DELETE), and every request is stateless: it carries all the information the server needs.

REST's strength is uniformity. Because it reuses HTTP semantics, it works with every client, proxy, and CDN, and responses can be cached with standard headers. Its weaknesses are over-fetching and under-fetching (returning too much or needing several calls), which GraphQL and gRPC address in different ways.

When to use it

• Public APIs consumed by many different clients.
• CRUD-style domains (users, products, orders).
• When HTTP caching and CDN support matter.
• Simple integration with browsers, mobile apps, and partners.

Where it shows up in interviews

Where it is used in real software

Key terms

Resource

A noun addressed by a URL: /orders/9001.

Stateless

The server keeps no client session between requests; each request is self-contained.

Idempotency

PUT and DELETE can be repeated safely; POST needs an idempotency key.

HATEOAS

Responses include links to related actions; rarely fully implemented in practice.

Cursor pagination

Clients page with an opaque cursor instead of page numbers.

Designing a REST resource

1. 1
   Name resources as plural nouns

   /orders, /orders/{id}, /users/{id}/orders. Avoid verbs like /getOrders.

2. 2
   Map actions to methods

   GET list or item, POST create, PATCH update, DELETE remove.

3. 3
   Choose status codes

   201 with Location on create, 204 on delete, 400/404/409 for client errors.

4. 4
   Support filtering and pagination

   GET /orders?status=paid&limit=50&cursor=abc.

5. 5
   Version and document

   /v1/ prefix or a version header, with an OpenAPI spec.

Endpoints for an orders resource

Consistent URLs, methods, and responses

Business actions that are not simple CRUD (cancel, refund) are often modeled as sub-resources or POST actions; consistency matters more than purity.

Implementation

1import express from "express";2 3const app = express();4app.use(express.json());5 6app.get("/v1/orders", async (req, res) => {7  const limit = Math.min(Number(req.query.limit ?? 50), 100);8  const { items, nextCursor } = await orders.list({ cursor: req.query.cursor as string, limit });9  res.json({ data: items, next_cursor: nextCursor });10});11 12app.post("/v1/orders", async (req, res) => {13  const key = req.header("Idempotency-Key");14  if (!key) return res.status(400).json({ error: "Idempotency-Key required" });15  const existing = await idempotency.get(key);16  if (existing) return res.status(existing.status).json(existing.body); // replay17 18  const order = await orders.create(req.body);19  await idempotency.save(key, { status: 201, body: order });20  res.status(201).location(`/v1/orders/${order.id}`).json(order);21});22 23app.delete("/v1/orders/:id", async (req, res) => {24  await orders.cancel(req.params.id);25  res.status(204).end();26});

Complexity and performance

Trade-offs

Variants and related techniques

Common mistakes

• Verbs in URLs (/createOrder).

  Fix: Use nouns and HTTP methods: POST /orders.

• Returning unbounded lists.

  Fix: Always paginate and cap the limit.

• Breaking changes without versioning.

  Fix: Add fields freely; remove or rename only in a new version.

Interview questions

Practice problems