REST API Design

Backend Fundamentals · Core Backend Fundamentals · 9 min read

1. What problem does this solve?

If a backend does not follow REST principles, developers often end up with:

• Hard‑to‑scale monoliths that need session affinity.
• APIs that are difficult to document and test.
• Clients that break when the server changes.

RESTful design is the backbone of most modern web services: Twitter, GitHub, Stripe, and many internal microservices use it.

2. Mental model

Analogy – The Library

Engineering model

• Resources are the domain entities exposed by the API (users, orders, posts).
• URIs uniquely identify each resource or collection.
• HTTP verbs map to CRUD operations, but also convey intent (safe, idempotent, cacheable).
• Representations are JSON, XML, or other media types; the API negotiates which one the client wants.
• Statelessness means the server does not keep session data between requests; everything is in the request/response.

3. Deep explanation

Internals

1. HTTP/1.1 or HTTP/2 – the transport layer; supports pipelining, multiplexing, and header compression.
2. Status codes – 2xx success, 3xx redirection, 4xx client error, 5xx server error.
3. Headers – Content-Type, Accept, ETag, Cache-Control, Authorization, etc.
4. Middleware pipeline – authentication, validation, logging, rate limiting, etc.
5. Routing – maps URI + verb to controller logic.

Important terminology

Trade‑offs

Failure modes

• Missing idempotency → duplicate side effects on retries.
• Over‑exposed endpoints → security holes.
• Improper caching → stale data.
• Large payloads → slow responses, high bandwidth.

Limitations

• Not ideal for highly interactive, real‑time workflows (WebSockets, gRPC).
• Complex business processes may require multiple round‑trips or stateful orchestration.

Where it fits

• API Gateway – routes requests to microservices.
• Service Mesh – handles inter‑service communication.
• Database Layer – CRUD operations are translated into SQL/NoSQL queries.
• Cache Layer – Redis or CDN for GET responses.

Interaction with related concepts

• Authentication – JWT, OAuth2, API keys.
• Rate limiting – per‑IP or per‑user quotas.
• Monitoring – Prometheus metrics, OpenTelemetry traces.
• CI/CD – contract tests (e.g., Pact) to ensure API stability.

4. How it works

1. Client sends an HTTP request (GET /users/42).
2. API Gateway / Load Balancer forwards to an instance of the service.
3. Middleware authenticates, authorizes, validates, logs.
4. Controller interprets the request, calls the Service layer.
5. Service contains business logic, may call Repository.
6. Repository performs database operations (PostgreSQL, MongoDB).
7. Result is returned to the controller, serialized to JSON.
8. Response is sent back to the client with appropriate status code and headers.

sequenceDiagram
    participant Client
    participant Gateway
    participant Auth
    participant Controller
    participant Service
    participant Repo
    participant DB

    Client->>Gateway: GET /users/42
    Gateway->>Auth: Validate token
    Auth-->>Gateway: OK
    Gateway->>Controller: Route to getUser
    Controller->>Service: getUser(42)
    Service->>Repo: findById(42)
    Repo->>DB: SELECT * FROM users WHERE id=42
    DB-->>Repo: row
    Repo-->>Service: user
    Service-->>Controller: user
    Controller->>Client: 200 OK + JSON

5. Practical implementation

Below is a minimal, production‑ready REST API using Fastify (fast, low‑overhead) and TypeScript.
It demonstrates routing, validation, error handling, pagination, and a simple in‑memory store.

// src/server.ts
import Fastify from 'fastify';
import { z } from 'zod';
import { UserService } from './services/userService';

const app = Fastify({
  logger: true,
  ignoreTrailingSlash: true,
});

const userSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(1),
  email: z.string().email(),
});

const userCreateSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});

const userService = new UserService();

/**
 * GET /users
 * Query: page, limit
 */
app.get('/users', async (req, reply) => {
  const { page = 1, limit = 10 } = req.query as any;
  const users = await userService.list({ page, limit });
  reply.code(200).send(users);
});

/**
 * GET /users/:id
 */
app.get('/users/:id', async (req, reply) => {
  const { id } = req.params as any;
  const user = await userService.get(id);
  if (!user) return reply.code(404).send({ error: 'Not found' });
  reply.code(200).send(user);
});

/**
 * POST /users
 */
app.post('/users', async (req, reply) => {
  const body = userCreateSchema.parse(req.body);
  const user = await userService.create(body);
  reply.code(201).send(user);
});

/**
 * PUT /users/:id
 */
app.put('/users/:id', async (req, reply) => {
  const { id } = req.params as any;
  const body = userCreateSchema.parse(req.body);
  const user = await userService.update(id, body);
  if (!user) return reply.code(404).send({ error: 'Not found' });
  reply.code(200).send(user);
});

/**
 * DELETE /users/:id
 */
app.delete('/users/:id', async (req, reply) => {
  const { id } = req.params as any;
  const ok = await userService.delete(id);
  if (!ok) return reply.code(404).send({ error: 'Not found' });
  reply.code(204).send();
});

const start = async () => {
  try {
    await app.listen({ port: 3000, host: '0.0.0.0' });
    console.log('Server listening on http://localhost:3000');
  } catch (err) {
    app.log.error(err);
    process.exit(1);
  }
};
start();

// src/services/userService.ts
import { v4 as uuidv4 } from 'uuid';
import { z } from 'zod';

export type User = z.infer<typeof userSchema>;
const userSchema = z.object({
  id: z.string().uuid(),
  name: z.string(),
  email: z.string().email(),
});

export class UserService {
  private store = new Map<string, User>();

  async list({ page, limit }: { page: number; limit: number }) {
    const all = Array.from(this.store.values());
    const start = (page - 1) * limit;
    return all.slice(start, start + limit);
  }

  async get(id: string) {
    return this.store.get(id) ?? null;
  }

  async create({ name, email }: { name: string; email: string }) {
    const id = uuidv4();
    const user: User = { id, name, email };
    this.store.set(id, user);
    return user;
  }

  async update(id: string, { name, email }: { name: string; email: string }) {
    if (!this.store.has(id)) return null;
    const user: User = { id, name, email };
    this.store.set(id, user);
    return user;
  }

  async delete(id: string) {
    return this.store.delete(id);
  }
}

Why this example is realistic

• Uses Fastify’s built‑in schema validation (via zod) for request bodies.
• Implements proper status codes (201, 204, 404).
• Keeps the service stateless – the in‑memory store is just for demo; in prod you’d plug in PostgreSQL or MongoDB.
• Demonstrates pagination and error handling.

6. Production considerations

7. Common mistakes

8. Senior engineer perspective

What changes at scale?

Bottlenecks

• Database – slow queries, lack of indexes, connection pool exhaustion.
• Serialization – JSON.stringify on large payloads.
• Network – latency between services, especially in multi‑region setups.

Failure scenarios

• Partial failures – one microservice down → graceful degradation.
• Network partitions – use retries with exponential backoff.
• Data inconsistency – eventual consistency vs strong consistency trade‑off.

Monitoring & Cost

• Metrics: request latency, error rates, throughput.
• Alerts: high error rate, slow response times.
• Cost: compute (K8s nodes), storage (DB, cache), network egress.
• Optimization: auto‑scaling, spot instances, request batching.

When NOT to use REST

• Real‑time, bidirectional communication – WebSockets or gRPC.
• Complex workflows – consider saga patterns or workflow engines.
• Heavy binary payloads – use multipart or dedicated file services.

9. Interview questions

10. Hands‑on task

Build a “Todo” REST API

1. Create a new Fastify project (or use the repo’s src/server.ts).
2. Implement CRUD endpoints for /todos with the following fields: id, title, completed, createdAt.
3. Add pagination to GET /todos.
4. Validate request bodies with zod.
5. Return proper status codes (201, 204, 404, 400).
6. Write a simple integration test using tap or jest that covers:
   • Creating a todo.
   • Retrieving it.
   • Updating it.
   • Deleting it.
7. Run the API locally, test with Postman or curl.

Bonus: Add a Redis cache for GET /todos/:id and invalidate on update/delete.

11. Quick revision

• REST = Resource‑Oriented, stateless, HTTP‑based API.
• Resources identified by URIs; verbs map to CRUD.
• Safe (GET, HEAD), idempotent (PUT, DELETE), cacheable (GET).
• Use status codes: 200, 201, 204, 400, 401, 403, 404, 429, 500.
• Validate input (zod, Joi) and output; never trust client data.
• Implement pagination (page, limit) for collections.
• Versioning: URI (/v1/) or header; keep old versions alive.
• Security: HTTPS, auth (JWT/OAuth2), rate limiting, CORS.
• Observability: structured logs, metrics, traces.
• Error handling: consistent JSON payload, avoid stack traces.
• Scalability: stateless services, horizontal scaling, caching.

12. References

• RFC 7231 – Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
• Fastify Docs – Validation & Schema
• OpenAPI Specification
• OWASP API Security Top 10
• Prometheus – HTTP Exporter
• OpenTelemetry – Node.js
• Zod – TypeScript Schema Validation
• JWT Handbook – RFC 7519