Chapter 6 — CRUD & REST API Design

The why

90% of backend code is CRUD. Create, Read, Update, Delete. Master this pattern once — the rest of your career is variations on it.

CRUD mapped to REST

For a resource notes:

Memorize this table. It's the grammar of every REST API.

Building a real CRUD resource

We'll build /notes in-memory (we'll switch to Postgres in P1):

const router = require('express').Router();
const crypto = require('crypto');
 
let notes = []; // in-memory store
 
// CREATE
router.post

Wire it in:

app.use('/notes', require('./routes/notes'));

Test with curl:

# Create
curl -X POST -H "Content-Type: application/json" \
  -d '{"title":"Hello"}' http://localhost:3000/notes
 
# List
curl http://localhost:3000/notes

This is a full CRUD resource. We'll add validation and persistence in the next chapters.

Status code cheat sheet (re-stated for muscle memory)

If you're unsure between 400 and 422: 400 = "I can't even parse this." 422 = "I parsed it, but it failed business rules."

PUT vs PATCH — when to use which

PUT replaces the entire resource. If the body omits a field, the field becomes null/missing.

PATCH is a partial update. Only fields present in the body change. The rest stay.

In practice, PATCH is what you usually want. PUT semantics break easily — clients forget a field, and your record loses data.

Some specs (JSON Patch, JSON Merge Patch) formalize PATCH bodies. For most apps, "the body has the fields to change" is fine.

Bulk operations

Often you want to create / update / delete many at once. Three options:

1. Loop POSTs on the client. Simple, slow, N requests.

2. Bulk endpoint:

POST /notes/bulk
[{ "title": "A" }, { "title": "B" }, { "title": "C" }]

Returns:

{
  "created": [...3 notes],
  "errors": []
}

3. Bulk with mixed results. When some succeed and some fail — return a 207 (Multi-Status) or a 200 with per-item status. Don't 500 the whole call because one item is bad.

Pagination — the right way

Offset pagination — ?page=3&limit=20 — easy, but slow at scale (page 1000 = OFFSET 20000, full scan).

Cursor pagination — ?cursor=abc123&limit=20 — fast at any scale. Cursor is an opaque identifier (usually the last item's ID or sortKey).

For your first 10,000 records, offset is fine. After that, switch to cursor.

{
  "data": [...],
  "nextCursor": "abc123",
  "hasMore": true
}

The client uses nextCursor for the next page. When it's null, you've reached the end.

Filtering, sorting, projecting

Query strings are the standard for all three.

GET /notes?status=published&author=42&sort=-createdAt&fields=id,title,body

• status=published&author=42 — filters
• sort=-createdAt — sort by createdAt, descending (- prefix = desc)
• fields=id,title,body — return only these fields (projection)

Tip: never blindly translate query params into SQL. Whitelist field names; treat values as parameterized.

Versioning — plan for the day you'll break things

Three styles:

In practice URL versioning wins. It's the easiest to operate. Start with /api/v1 on day one even if you'll never need v2.

When you do release v2:

• Keep v1 running for 6–12 months.
• Add a Sunset header to v1 responses warning of removal date.
• Announce broadly.
• Watch metrics; remove v1 only when traffic drops to ~zero.

Idempotency

A safe-to-retry operation is idempotent: running it twice has the same effect as once.

• GET, PUT, DELETE — naturally idempotent.
• POST — usually not.

If a POST is critical (charge a card), make it idempotent with an idempotency key:

POST /payments
Idempotency-Key: 9c5...
 
{ "amount": 1000, "currency": "INR" }

Server stores the key + result. Second call with same key returns the cached result. Stripe does this — copy the pattern.

Common mistakes

Production · Performance · Security notes

Production. Always return the created resource (or its ID + Location header) on POST. Frontends need it immediately.

Performance. GET endpoints should be cacheable. Set Cache-Control thoughtfully. POST/PATCH/DELETE never cache.

Security. Authorize per record. A logged-in user with GET /notes/42 should only see notes they own (or were shared).

Exercises

1. Beginner. Add a category field to notes. Filter by it: GET /notes?category=work.
2. Beginner. Implement PUT (full replace). Pick what should happen if a field is omitted.
3. Intermediate. Implement cursor pagination using the note's createdAt as the cursor.
4. Intermediate. Add an idempotency-key middleware to your POST endpoint.
5. Advanced. Design a soft-delete: DELETE marks deletedAt, GET filters them out. Add an ?includeDeleted=true for admins.

Interview questions

Beginner. What's the right status code for "I created the thing"? 201, ideally with a Location header.

Senior. How would you version an API in a backwards-compatible way? URL versioning, dual-running v1 + v2, Sunset header, deprecation notices, monitoring of v1 traffic before removal.

Summary

CRUD is the spine of every API. Map operations to HTTP methods correctly, return the right status, paginate with cursors, version from day one, support idempotency where it matters. The pattern is small; doing it cleanly is what separates a junior API from a senior one.

Quick recall

• CRUD = Create, Read, Update, Delete → POST, GET, PATCH/PUT, DELETE.
• 201 Created with Location header for POST.
• 204 No Content for DELETE.
• PATCH > PUT for everyday updates.
• Cursor pagination > offset at scale.
• /api/v1 from day one.

Quiz

1. Right status for a successful DELETE?
2. PATCH vs PUT — which is partial?
3. What header confirms the URL of a newly created resource?
4. Why is offset pagination slow at scale?
5. What is an idempotency key for?