Let's Build a Backend

Md Touhidul Islam

Goal by the end:

A small REST API: /notes
Data stored in data/notes.json (no database)

Step 0: Project folder structure

✅ Create these folders/files

backend-notes/
backend-notes/src/server.mjs
backend-notes/data/notes.json
backend-notes/package.json

✅ What is this API?

GET /health → quick server check
GET /notes → list notes
POST /notes → create
GET /notes/:id → read one
PUT /notes/:id → update
DELETE /notes/:id → delete

Why JSON file? It forces us to learn how backends do persistence: validate input → read current state → modify → write back atomically → return response.

Step 1: package.json + scripts

We’ll run the server with npm run dev (auto-restart) and npm start (normal).
Use ESM (.mjs) so import works naturally.

COPY-PASTE: package.json

Ln 1, Col 1JSON

Run these in terminal:

npm install
npm run dev

Step 2: Create the first server (health route)

Start with the smallest possible backend that proves: Node can accept a request and return JSON.
Everything after this is “just” adding capability on top of a working baseline.

COPY-PASTE: src/server.mjs (v1)

Ln 1, Col 1JavaScript (Node)

What changed (vs nothing):

We created one endpoint: GET /health
We return a JSON response with status 200
Unknown routes return 404

From now on: every step should keep /health working. If it breaks, rollback and fix.

Test:

curl http://localhost:3000/health
Expected: {"ok":true}

Step 3: Add response helpers (consistent JSON)

Backends repeat the same response patterns hundreds of times.
We extract helpers so every endpoint returns consistent headers + JSON shape.

COPY-PASTE: src/server.mjs (v2)

Ln 1, Col 1JavaScript (Node)

What changed from v1 (look for highlighted lines):

json(res, status, payload) — one function to set JSON headers + stringify
notFound(res) — one place for the standard 404 response
Benefit: future routes stay small and readable (no repeated boilerplate)

In the editor, any line tagged with // NEW / // CHANGED is highlighted.

Step 4: Read request body (POST needs it)

A real backend must accept data from the client (POST/PUT).
Node request bodies are streams → we collect chunks and then parse JSON.

COPY-PASTE: src/server.mjs (v3)

Ln 1, Col 1JavaScript (Node)

What changed from v2:

readBody(req) added to read streaming request bodies
new URL(req.url, ...) added (clean path parsing)
New practice route: POST /echo returns the JSON you sent

Test:

curl -X POST http://localhost:3000/echo -H "Content-Type: application/json" -d '{"msg":"hi"}'
Expected: {"received":{"msg":"hi"}}

Step 5: Create the JSON “database” file

Start with an empty array. Every note will be an object with id, text, createdAt, updatedAt.

COPY-PASTE: data/notes.json

Ln 1, Col 1JSON

Important: This “JSON file DB” is good for learning, not production. Concurrency is tricky (two requests writing at the same time). We’ll still build it correctly for class.

Step 6: Load + save notes from the JSON file

Now the backend needs persistence (state survives restarts).
We’ll treat data/notes.json as our “database”.

COPY-PASTE: src/server.mjs (v4)

Ln 1, Col 1JavaScript (Node)

What changed from v3:

Added loadNotes() and saveNotes() using fs/promises
Added NOTES_PATH built from import.meta.url so it works from any working directory
Added first real resource endpoint: GET /notes

Backend pattern: read current state → compute new state → write back → respond.

Test:

curl http://localhost:3000/notes → [] (for now)

Step 7: POST /notes (Create a note)

Create means: validate input → add a new object → persist to file → return the created resource.
We also generate ids that stay correct after restart.

COPY-PASTE: src/server.mjs (v5)

Ln 1, Col 1JavaScript (Node)

What changed from v4:

Re-introduced readBody() (we need it for POST)
Added nextId(notes) (max+1) so ids survive server restarts
Added POST /notes with validation (text required)

Test:

curl -X POST http://localhost:3000/notes -H "Content-Type: application/json" -d '{"text":"first note"}'
Then: curl http://localhost:3000/notes

Step 8: GET /notes/:id (Read one note)

We need a route parameter: /notes/3 means “note with id=3”.
If the id is invalid → 400; if not found → 404.

COPY-PASTE: src/server.mjs (v6)

Ln 1, Col 1JavaScript (Node)

What changed from v5:

Added parseId() to extract ids from paths
Added GET /notes/:id and implemented “not found” logic

Route params are core backend skill: almost every REST API uses them.

Test:

curl http://localhost:3000/notes/1
curl http://localhost:3000/notes/999 → 404

Step 9: PUT /notes/:id (Update)

Update means: find resource → validate input → mutate → persist → return updated resource.
We also update updatedAt.

COPY-PASTE: src/server.mjs (v7)

Ln 1, Col 1JavaScript (Node)

What changed from v6:

Added PUT /notes/:id
Validated text again (never trust client input)
Persisted back to notes.json

Test:

curl -X PUT http://localhost:3000/notes/1 -H "Content-Type: application/json" -d '{"text":"updated note"}'
curl http://localhost:3000/notes/1

Step 10: DELETE /notes/:id (Delete)

Delete means: confirm it exists → remove it → persist → return a clear status code.
REST convention: return 204 No Content on success.

COPY-PASTE: src/server.mjs (v8)

Ln 1, Col 1JavaScript (Node)

What changed from v7:

Added DELETE /notes/:id
On success: no JSON body, status 204

Test:

curl -i -X DELETE http://localhost:3000/notes/1 → status 204
curl http://localhost:3000/notes

Step 12: Add CORS (only if you plan a browser frontend)

Browsers block cross-origin requests unless the server allows them (CORS).
If you only test with curl/Postman, you can skip this step.

COPY-PASTE: src/server.mjs (v9 - with CORS)

Ln 1, Col 1JavaScript (Node)

What changed from v8:

Added setCors(res) headers
Handled OPTIONS preflight requests
Made PORT configurable (env var)

In production, never allow every origin. Restrict to the frontend domain(s).

Quick test suite (copy these curl commands)

COPY-PASTE: terminal commands

Ln 1, Col 1Text

When a backend “works”, it means:

Correct status codes
Correct JSON response shapes
Data actually persists after restart

Practice problems

Possible backend extensions:

Search: GET /notes?contains=word filters notes by substring (case-insensitive)
Limit: GET /notes?limit=5 returns only the first N notes
Sort: GET /notes?order=desc returns newest notes first
Count: GET /notes/count returns {"count": number}
Validation: invalid limit values return 400 Bad Request
Timestamp filter: GET /notes?updatedAfter=TIMESTAMP returns recently updated notes only

Useful query-parameter pattern:

const url = new URL(req.url, 'http://localhost');
url.searchParams.get('contains')
url.searchParams.get('limit')

Full final code (one last time)

FINAL: src/server.mjs

Ln 1, Col 1JavaScript (Node)

FINAL: data/notes.json

Ln 1, Col 1JSON