DEV Community: Akhileswar Sathivada

Authentication vs Authorization: Who Are You, and What Can You Do?

Akhileswar Sathivada — Mon, 02 Nov 2026 05:14:46 +0000

Imagine logging into an application.

You enter your email and password, click Login, and land on your dashboard. Everything works as expected.

Now, suppose you try accessing the admin dashboard, but the application denies access.

You're already logged in. So why can't you access it?

Because knowing who you are and deciding what you're allowed to do are two different things.

This is where Authentication and Authorization come in. They are two fundamental concepts in backend development, and almost every application that handles users relies on them.

Although they often work together, they solve two completely different problems.

1. Authentication: Who Are You?

Authentication is the process of verifying the identity of a user or system.

It answers one simple question:

"Are you really who you claim to be?"

Think about what happens when you log into an application. You provide credentials such as:

Email address
Password
One-time password (OTP)
Biometric information

The backend receives the credentials and verifies them against the information stored for that user.

For example, consider a login request:

{
  "email": "alex@example.com",
  "password": "mypassword"
}

The backend checks whether the supplied credentials are valid. In a properly secured application, passwords are stored as password hashes rather than plain text, and the submitted password is verified against the stored hash.

If verification succeeds, the backend establishes an authenticated identity for the user.

The application now knows that the request belongs to Alex.

But here's an important question:

Does successfully logging in mean Alex can access everything in the application?

Not necessarily.

That's where authorization comes in.

2. Authorization: What Can You Do?

Authorization determines what an authenticated user is allowed to access or perform.

It answers a different question:

"Given who you are, what are you allowed to do?"

Let's take an example of an e-commerce application with three types of users:

User	Permissions
Customer	Browse products, place orders, view their own orders
Manager	Manage inventory, view orders, update product details
Admin	Manage users, products, orders, and application settings

All three users can successfully log in.

Authentication establishes their identities, but authorization determines what actions each user can perform.

For example, a customer might successfully log in and view their orders. However, if they try to delete another user's account, the backend should reject the request.

The customer is authenticated, but they aren't authorized to perform that operation.

This distinction is important because being authenticated doesn't automatically mean being authorized.

3. How Do Authentication and Authorization Work Together?

Let's connect these concepts through a typical backend request.

Suppose Alex logs into an application and tries to access an administrative API.

The backend follows two important steps:

Authentication: Verify Alex's identity.
Authorization: Check whether Alex has permission to access the requested resource.

The simplified flow looks like this:

             USER
               |
               v
          LOGIN REQUEST
               |
               v
        AUTHENTICATION
        Verify Identity
               |
          Is Identity
             Valid?
           /       \
         No         Yes
         |           |
         v           v
       Reject    Authenticated
       Request       User
                       |
                       v
                  API REQUEST
                       |
                       v
                 AUTHORIZATION
                Check Permissions
                       |
                 Is Access Allowed?
                    /       \
                  No         Yes
                  |           |
                  v           v
               Reject     Process
               Request    Request

There are two separate decisions being made:

Is this request associated with a verified identity?
Is that identity allowed to perform the requested operation?

If authentication fails, the backend cannot establish the identity needed for an authenticated operation.

If authentication succeeds but authorization fails, the user is recognised but doesn't have the required permission.

This separation allows applications to manage user identity and access control independently.

4. Understanding 401 and 403

While working with APIs, you'll frequently encounter two HTTP status codes related to access control:

401 Unauthorized

Despite its name, 401 Unauthorized generally means that the request lacks valid authentication credentials.

For example:

A user hasn't logged in.
An authentication token is missing.
A token is expired or invalid.

The backend cannot establish a valid authenticated identity for the request.

403 Forbidden

403 Forbidden means the server understood the request but refuses to allow the requested operation.

For example:

A customer tries accessing an admin-only API.
A user attempts to modify a resource they don't have permission to modify.

In this case, the user may already be authenticated, but they don't have the required permissions.

A simple way to remember the difference:

401: The request isn't properly authenticated.
403: The request is authenticated, but access is not permitted.

5. Where Should These Checks Happen?

One common mistake in application development is relying entirely on the frontend to control access.

Imagine an application that hides the Delete User button from regular customers.

It might seem secure because customers cannot see or click the button.

But the frontend is not a security boundary.

A user can inspect the application's code, modify client-side state, or send an API request directly using tools such as Postman or cURL.

For example:

DELETE /api/users/42

Even if the frontend hides this operation, the backend endpoint still exists.

If the backend doesn't verify the user's permissions, an unauthorized user might successfully perform the operation.

That's why authentication and authorization checks must be enforced on the backend.

The frontend can improve the user experience by hiding unavailable features, but the backend must make the final access decision.

6. The Key Takeaway

Authentication and authorization are closely related, but they shouldn't be treated as the same thing.

Think of entering an office building.

Your identity card helps establish who you are. But having an identity card doesn't mean you can enter every room.

Some rooms require additional permissions based on your role.

That's authentication and authorization working together.

Authentication	Authorization
Verifies identity	Checks permissions
Answers "Who are you?"	Answers "What can you do?"
Uses credentials and identity verification	Uses roles, permissions, and access rules
Establishes an authenticated identity	Determines access to protected operations

Both are essential for building secure backend applications.

Authentication establishes trust in an identity, while authorization determines what that identity is allowed to do.

What's Next?

Now that we understand how a backend identifies users and controls their access, there's another interesting question:

How does a backend remember that you've already logged in?

HTTP is stateless. Every request is independent, so how does a server recognise you when you navigate to another page or make another API request?

That's where sessions, cookies, and tokens enter the picture.

Next in the series: How Backend Authentication Evolved - From Passwords to Sessions and JWTs.

Serialization and Deserialization: How Data Travels Between Frontend and Backend

Akhileswar Sathivada — Sat, 31 Oct 2026 12:28:07 +0000

Imagine you're building a web application using React for the frontend and Go for the backend.

A user fills out a form, clicks Submit, and expects the backend to save the information.

The frontend has the data. The backend needs the data. So why can't we simply send the JavaScript object directly to the Go server?

Because the frontend and backend don't necessarily represent data in the same way.

They use different programming languages, different data structures, and different runtime environments. They need a common format to exchange information.

This is where serialization and deserialization come in.

1. The Communication Problem

Let's say a user enters the following details:

const user = {
  name: "Alex",
  age: 24,
  isDeveloper: true
};

Inside JavaScript, this is an object.

But the backend might be written in Go, Python, Java, or another language. Each language has its own way of representing objects and structures.

A JavaScript object isn't automatically a Go struct. The backend cannot simply receive the in-memory JavaScript object and use it.

We need to convert the data into a format that both systems understand.

For most web APIs, that format is JSON.

2. What Is Serialization?

Serialization is the process of converting data structures or objects into a format that can be stored or transmitted.

In our example, we convert the JavaScript object into a JSON string.

const user = {
  name: "Alex",
  age: 24,
  isDeveloper: true
};

const serializedUser = JSON.stringify(user);

console.log(serializedUser);

Output:

{
  "name": "Alex",
  "age": 24,
  "isDeveloper": true
}

The JavaScript object has now been converted into a JSON representation.

This representation can be sent over HTTP, stored in a file, or passed to another system.

Notice the difference:

Before serialization: We have a JavaScript object in memory.
After serialization: We have a JSON string representing that object.

Serialization doesn't send the original object itself. It creates a representation of the data.

3. What Is Deserialization?

Now let's look at the backend side.

The backend receives the JSON data. But it needs to convert that representation into something it can work with in its own programming language.

Deserialization is the process of converting serialized data back into a usable data structure or object.

For example, imagine our backend is written in Go.

We can define a struct to represent the incoming data:

type User struct {
    Name        string `json:"name"`
    Age         int    `json:"age"`
    IsDeveloper bool   `json:"isDeveloper"`
}

The backend can decode the incoming JSON into this struct:

var user User

err := json.NewDecoder(r.Body).Decode(&user)

if err != nil {
    http.Error(w, "Invalid request body", http.StatusBadRequest)
    return
}

fmt.Println(user.Name)

The JSON data has now been converted into a Go struct.

The backend can access the values using Go's normal syntax.

One important detail: deserialization can fail. For example, the incoming JSON might be malformed or contain values that cannot be decoded into the expected Go types.

That's why backend applications should handle decoding errors rather than assuming every request contains valid data.

4. Following the Complete Request-Response Cycle

Let's connect both concepts.

Suppose a React application sends user information to a Go backend.

The process looks like this:

Frontend

const user = {
  name: "Alex",
  age: 24,
  isDeveloper: true
};

const response = await fetch("/api/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify(user)
});

Here's what happens:

React has a JavaScript object.
JSON.stringify() serializes the object into JSON text.
The browser sends the JSON as the HTTP request body.
The Go backend receives the request.
json.NewDecoder() deserializes the JSON into a Go struct.
The backend processes the data.

The reverse happens when the backend sends a response.

Backend

response := User{
    Name:        "Alex",
    Age:         24,
    IsDeveloper: true,
}

w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(response)

The Go struct is serialized into JSON and written to the HTTP response.

Frontend

const data = await response.json();

console.log(data.name);

The browser reads the JSON response and converts it into a JavaScript value.

Complete Flow

       REACT FRONTEND
              |
       JavaScript Object
              |
       JSON.stringify()
              |
        Serialized JSON
              |
          HTTP Request
              |
              v
         GO BACKEND
              |
       JSON Decoder
              |
          Go Struct
              |
       Backend Processing
              |
          Go Struct
              |
       JSON Encoder
              |
        Serialized JSON
              |
         HTTP Response
              |
              v
       REACT FRONTEND
              |
        response.json()
              |
       JavaScript Object

The important thing to understand is that serialization and deserialization happen in both directions.

The frontend serializes data when sending a request and deserializes data when receiving a response. The backend does the opposite.

5. Why JSON?

JSON stands for JavaScript Object Notation.

Despite its name, JSON isn't limited to JavaScript. It is a language-independent data-interchange format supported by many programming languages.

For example:

JavaScript uses JSON.stringify() and JSON.parse().
Go provides the encoding/json package.
Python provides the built-in json module.
Java has libraries such as Jackson for JSON processing.

JSON supports a small set of data types:

Strings
Numbers
Booleans
Arrays
Objects
Null

This makes it convenient for exchanging structured data between applications.

However, JSON doesn't preserve every detail of an application's original data structure.

For example, JavaScript has types such as Date, Map, and Set. JSON doesn't have direct equivalents for all of them. A date is commonly represented as a string, and special types need an agreed representation and conversion logic.

So serialization isn't always a perfect copy of an object. It is a conversion into a format that both sides agree to understand.

6. What Happens When the Data Doesn't Match?

Let's say the frontend sends:

{
  "name": "Alex",
  "age": "twenty-four",
  "isDeveloper": true
}

But the Go backend expects:

type User struct {
    Name        string `json:"name"`
    Age         int    `json:"age"`
    IsDeveloper bool   `json:"isDeveloper"`
}

The age field is a string in the incoming JSON, but the backend expects an integer.

Go's JSON decoder cannot decode that string into an int automatically. It returns an error.

This is one reason backend developers validate incoming data.

There are two separate concerns here:

Deserialization: Can the incoming representation be converted into the expected data structure?

Validation: Does the resulting data satisfy the application's requirements?

For example, even if age is successfully decoded as an integer, the application may still reject a negative age.

Successful deserialization doesn't automatically mean the data is valid or safe to use.

7. Is JSON the Only Serialization Format?

No. JSON is popular, particularly for web APIs, but there are other formats.

Format	Common Use
JSON	REST APIs and general web communication
XML	Legacy systems and document-oriented data exchange
Protocol Buffers	Efficient structured communication, often in gRPC systems
MessagePack	Compact binary serialization
Avro	Data serialization in distributed data pipelines

Different formats make different trade-offs.

For example, JSON is human-readable and easy to debug. Protocol Buffers use a compact binary representation and a schema, which can be useful when efficiency and strongly defined message structures matter.

The right format depends on the system, its requirements, and the technologies communicating with each other.

8. A Small Experiment to Understand the Difference

You don't need a complete frontend and backend application to understand the basic concept.

Try this in JavaScript:

const original = {
  name: "Alex",
  age: 24,
  skills: ["JavaScript", "Go"]
};

// Serialization
const serialized = JSON.stringify(original);

console.log("Serialized:", serialized);
console.log("Type:", typeof serialized);

// Deserialization
const deserialized = JSON.parse(serialized);

console.log("Deserialized:", deserialized);
console.log("Type:", typeof deserialized);

Observe the output.

The serialized value is a string. After parsing, you get a JavaScript object again.

Now try:

JSON.parse('{"name": "Alex", "age": }');

This will throw a parsing error because the JSON is malformed.

That small example demonstrates an important point: serialization and deserialization are conversions, and those conversions can fail.

9. What Should a Backend Developer Remember?

Serialization and deserialization are fundamental to communication between different parts of a software system.

Whenever an application exchanges structured data, it needs an agreed representation.

A few things worth remembering:

Serialization converts an in-memory data structure into a transferable or storable representation.
Deserialization converts that representation back into a usable data structure.
JSON is a common format, but it isn't the only option.
Both frontend and backend participate in this process.
Successful deserialization doesn't guarantee that the data is valid.
Backend applications should handle malformed input, type mismatches, and validation failures.

Final Thought

At first, serialization and deserialization might look like simple conversion operations.

But they're part of a much bigger idea: how independent systems communicate without needing to share the same programming language or internal data structures.

Your React frontend doesn't need to understand Go structs, and your Go backend doesn't need to understand JavaScript objects.

They only need to agree on how their data should be represented and exchanged.

That's one of the foundations of backend communication.

Next in the series: Authentication vs Authorization - how does a backend know who is making a request, and what are they allowed to do?

Backend from First Principles, Week 1: How the Web Actually Talks

Akhileswar Sathivada — Sun, 25 Oct 2026 15:27:24 +0000

This is the first entry in a weekly series where I turn backend
concepts into small experiments instead of stopping at definitions.

A request can look almost too simple:

const response = await fetch("https://api.example.com/products");
const products = await response.json();

Two lines of JavaScript. But those lines hide a surprising amount of
work: the browser applies its security rules, a hostname must be
resolved, a connection is established, HTTP metadata travels with the
request, a server chooses a route, application code runs, and a response
makes its way back.

When something goes wrong, the browser might show a CORS error, a 401,
a 304, or a response that seems to have disappeared. Those messages
can feel unrelated. They become easier to debug when we stop treating an
API call as a single action and start tracing the steps around it.

That is the goal of this week's lab: make the invisible parts of an
HTTP request observable.

I am learning these concepts as part of my backend-from-first-principles
study. The explanations below are written in my own words, and the
examples are designed to be reproducible. The most useful part is not
memorising every header; it is learning what to inspect when the
behaviour differs from what I expected.

1. Follow one request from the browser to the server

Imagine a frontend requesting:

GET /api/products/1 HTTP/1.1
Host: api.example.com
Accept: application/json

A typical request path might look like this:

DNS lookup: the client resolves api.example.com to an IP address. The answer may already be cached, so a DNS lookup is not necessarily performed for every request.
Connection and transport: the client establishes or reuses a connection. With HTTP/1.1 or HTTP/2, this commonly means TCP; HTTPS also involves TLS. HTTP/3 uses QUIC over UDP instead.
Network edge: depending on the deployment, the request may pass through a firewall, load balancer, CDN, or reverse proxy such as Nginx.
Application server: the request reaches the process listening for it. The application matches the method and path to a handler.
Application work: the handler validates input, applies business rules, and may read from or write to a database or another service.
Response: the server sends a status code, headers, and usually a body. The client then decides how to handle that response.

This is a mental model, not a fixed architecture. A small local Node
server may skip the proxy and cloud infrastructure entirely. A
production system may have several services between the browser and the
code that finally handles the request.

The practical debugging question is: which step did the request
reach? The browser's Network panel, server logs, and a command-line
client each reveal a different part of the story.

2. Why split frontend and backend?

Frontend code is delivered to a user's device and runs in an environment
the developer does not control. A user can inspect that code and modify
what happens locally. That makes the browser the wrong place to keep
secrets or enforce rules that must be trusted.

The backend is where a system can keep private credentials, enforce
permissions, validate important operations, and communicate with
databases using server-side connections. It can also perform work that
would be expensive or inappropriate for a user's device.

A useful rule of thumb:

The frontend handles presentation and user interaction.
The backend owns trusted application rules and mediates access to protected resources.
The database stores and retrieves persistent data, but should not be exposed directly to an untrusted browser.

This is not because frontend code is incapable of doing calculations. It
is because calculations and decisions that must be trusted need to be
enforced somewhere the user cannot simply rewrite.

CORS is related to browser security, but it is not a replacement for
authentication or authorization. We'll test that distinction shortly.

3. Read the HTTP message, not just the JSON

HTTP gives the client and server a shared format for describing a
request and its response. A simplified request might be:

PUT /api/users/123 HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer <token>

{"name":"Akhil"}

It has a request line, headers, a blank line, and an optional body. The
response has a status line, headers, a blank line, and usually a body:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{"id":123,"name":"Akhil"}

The JSON is only the body. The status and headers tell the client how to
interpret it.

A few headers worth recognising:

Content-Type describes the representation being sent, such as application/json.
Accept tells the server what response formats the client can accept.
Authorization carries credentials or a token.
Cache-Control describes caching rules.
ETag identifies a particular representation version for cache validation.
Content-Encoding describes a transformation such as gzip compression.

Headers are not decoration. They are part of the protocol, and changing
one can change how a browser or server behaves.

4. HTTP methods: intent matters

The common methods express different kinds of operations:

Method Typical intent Idempotent?

GET Read a representation Yes

POST Submit data or create a Not generally
resource

PUT Create or replace the Yes
target resource with

the supplied

representation

PATCH Apply a partial Depends on the patch
modification operation

DELETE Remove the target Yes
resource

Idempotent does not mean "returns the same response every time." It
means that repeating the same request has the same intended effect on
server state as making it once.

For example, setting a product's price to 600 repeatedly can leave the
product at 600. Creating an order repeatedly can create a new order
each time. A repeated DELETE can return a different status on the
second call while still being idempotent if the resource remains
deleted.

This distinction matters when designing retry behaviour. A network can
fail after a server has processed a request but before the client
receives the response. The client may not know whether the operation
happened. Blindly retrying a non-idempotent operation can create
duplicates; real payment or order systems often need explicit
idempotency keys and server-side handling.

5. CORS: the browser may hide a response the server sent

Browsers apply the same-origin policy. An origin is the combination of
scheme, host, and port, so http://localhost:5173 and
http://localhost:3001 are different origins even though both use
localhost.

Cross-Origin Resource Sharing (CORS) is a mechanism through which a
server tells a browser which origins may read a response. For a request
that does not require preflight, the browser can send the request and
then check the response's CORS headers before exposing the response to
JavaScript.

That creates a useful distinction:

The server may receive a request and send a response.
The browser may still refuse to expose that response to the page's JavaScript.

Some requests trigger a preflight: the browser first sends an
OPTIONS request asking whether the origin, method, and requested
headers are allowed. A JSON PUT or a request with an Authorization
header commonly triggers this check.

A simplified preflight looks like this:

OPTIONS /api/products/1 HTTP/1.1
Origin: http://localhost:5173
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: content-type

If the server approves it, the browser can proceed with the actual
request. If the preflight fails, the browser normally does not send that
actual request.

CORS is not authentication. A command-line tool such as curl does
not enforce browser CORS rules. A server must still authenticate callers
and check their permissions; CORS alone does not protect an API from
direct requests.

6. Status codes are clues, not complete explanations

The status code gives the client a broad category of outcome:

2xx --- success: 200 OK, 201 Created, 204 No Content.
3xx --- redirection or cache validation: 301, 302, 304 Not Modified.
4xx --- request or client-side problem: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 429 Too Many Requests.
5xx --- server-side failure or temporary unavailability: 500 Internal Server Error, 503 Service Unavailable.

Two common confusions are worth clearing up:

401 means valid authentication credentials are missing or unacceptable; 403 means the server refuses the action. In real applications, exact behaviour depends on the authentication scheme and API design.
A 404 does not prove that a server is down. It often means the server is reachable but the requested route or resource was not found.

A status code is one clue. Combine it with the response body, request
headers, server logs, and the route that handled the request.

7. Caching: sometimes the best request is no request

Caching allows a client to reuse a response rather than download the
same data repeatedly. For example:

Cache-Control: max-age=10, public
ETag: "abc123"

max-age=10 says that the response can be considered fresh for ten
seconds under the applicable caching rules. While a response is fresh,
the browser may reuse it without contacting the server.

After it becomes stale, the client can revalidate it:

If-None-Match: "abc123"

If the representation has not changed, the server can reply with
304 Not Modified. That response has no representation body; the client
reuses the body it already has. If the representation has changed, the
server sends a fresh response, commonly with 200 OK and a new ETag.

There are two behaviours to distinguish when debugging:

Fresh-cache reuse: the browser may make no network request at all.
Revalidation: the browser contacts the server, which can reply 304 or return a new representation.

Browser APIs such as fetch can make cache behaviour less obvious than
it looks in the Network panel. The lab below logs requests on the server
so we can compare what JavaScript receives with what actually reached
the server.

8. Representation, compression, uploads, and streaming

HTTP can carry more than one kind of payload. The headers help both
sides agree on how to interpret it.

Content negotiation: Accept and related headers express preferences about response formats, languages, or encodings. The server may choose among supported representations.
Compression: Accept-Encoding tells the server which content encodings the client supports. If the server compresses a suitable response, it identifies the encoding with Content-Encoding. Compression can reduce transferred bytes, but the result depends on the data, algorithm, and configuration.
Multipart uploads: multipart/form-data packages form fields and file content into parts separated by a boundary. It is common for browser file uploads.
Streaming: instead of waiting for the entire response body, a client can consume chunks as they arrive. Server-Sent Events (SSE) use text/event-stream for one-way updates from server to client.

Streaming is especially useful when waiting for the complete result
would make an interface feel slow. The client can begin displaying
progress or partial output while the server continues working. It is not
the same as simply returning a large JSON object: with ordinary JSON,
the client generally needs the complete body before parsing it as one
JSON value.

9. Routing and API versioning

A route maps an HTTP method and a path to a handler. The path can
identify a collection or a particular resource, while query parameters
often control filtering or pagination.

GET /api/books
GET /api/users/123
GET /api/search?q=backend&page=2&limit=10
GET /api/users/7/products/1

The path and query string serve different purposes. /api/users/123
identifies a user; ?page=2&limit=10 commonly describes how to retrieve
a slice of a collection.

APIs also evolve. If clients depend on a response containing name and
price, changing those fields in place can break them. One option is to
introduce a new version:

/api/v1/products/1 returns id, name, and price.
/api/v2/products/1 returns id, title, cost, and currency.

Versioning is not free: it adds maintenance work and old versions need a
deprecation plan. The point is to make incompatible changes deliberately
rather than accidentally breaking every existing client.

The experiment: make the request visible

Definitions are useful, but they do not always predict what the browser
will show. For the rest of this post, I use a small local playground to
test a few behaviours that are easy to misunderstand:

A request can reach the server even when browser JavaScript cannot read the response.
A preflight can fail before the actual request is sent.
A cache hit and a 304 revalidation are different events.
Repeating an idempotent request does not necessarily produce an identical response.
Compression and streaming are visible in the bytes transferred and the timing of chunks.

The lab is deliberately small and uses Node's built-in modules. It is
not a production server; it is a controlled environment for learning how
HTTP behaves.

The server below is intentionally compact: it includes a small router,
an in-memory product, example status endpoints, cache validation, gzip
compression, an SSE endpoint, and a request log. The data is reset
whenever the process restarts.

One important limitation: the /api/status/:code route is a
demonstration tool that returns the requested status code. Clicking
403 or 409 there does not reproduce every real-world permission or
conflict scenario; it lets you inspect how a client displays different
status codes. The /api/secure route is also only a toy example and
does not validate a real token.

server.js

// backend-lab/server.js
// Zero-dependency starter for the "Backend from First Principles" series.
//
//   node server.js
//   API  -> http://localhost:3001
//   Page -> http://localhost:5173   (a different origin on purpose, so CORS is real)

const http = require('http');
const fs = require('fs');
const path = require('path');
const zlib = require('zlib');
const crypto = require('crypto');

const API_PORT = Number(process.env.API_PORT) || 3001;
const WEB_PORT = Number(process.env.WEB_PORT) || 5173;
const ALLOWED_ORIGIN = process.env.ALLOWED_ORIGIN || `http://localhost:${WEB_PORT}`;

// ---------- in-memory "database" ----------
let product = { id: 1, name: 'iPhone', price: 500 };
const orders = [];
const catalog = Array.from({ length: 25 }, (_, i) => ({
  id: i + 1,
  name: `Item ${i + 1}`,
  price: 100 + i * 10,
}));
const requestLog = []; // what the server really saw (browsers hide some of it)

// ---------- helpers ----------
const etagOf = (s) =>
  '"' + crypto.createHash('sha1').update(s).digest('hex').slice(0, 8) + '"';

// Send JSON. Compresses with gzip when the client allows it and the body is big.
function send(req, res, status, data, headers = {}) {
  const raw = typeof data === 'string' ? data : JSON.stringify(data);
  let body = Buffer.from(raw);
  const h = { 'Content-Type': 'application/json', ...headers };
  if (body.length > 1024 && /\bgzip\b/.test(req.headers['accept-encoding'] || '')) {
    body = zlib.gzipSync(body);
    h['Content-Encoding'] = 'gzip';
  }
  res.rawBytes = Buffer.byteLength(raw);
  res.sentBytes = body.length;
  res.writeHead(status, h);
  res.end(body);
}

function readJson(req) {
  return new Promise((resolve, reject) => {
    let raw = '';
    req.on('data', (c) => (raw += c));
    req.on('end', () => {
      if (!raw) return resolve({});
      try {
        resolve(JSON.parse(raw));
      } catch {
        reject(Object.assign(new Error('Invalid JSON'), { status: 400 }));
      }
    });
  });
}

// ---------- tiny router: method + pattern -> handler ----------
const routes = [];
function route(method, pattern, handler) {
  const keys = [];
  const regex = new RegExp(
    '^' + pattern.replace(/:(\w+)/g, (_, k) => (keys.push(k), '([^/]+)')) + '$'
  );
  routes.push({ method, regex, keys, handler });
}

// Static, path params, query params, nested resources
route('GET', '/api/v1/products', ({ req, res, query }) => {
  const page = Math.max(1, Number(query.get('page')) || 1);
  const limit = Math.min(50, Math.max(1, Number(query.get('limit')) || 10));
  send(req, res, 200, {
    page,
    limit,
    total: catalog.length,
    items: catalog.slice((page - 1) * limit, page * limit),
  });
});

// v1 supports HTTP caching (ETag + Cache-Control)
route('GET', '/api/v1/products/:id', ({ req, res, params }) => {
  if (Number(params.id) !== 1) return send(req, res, 404, { error: 'Product not found' });
  const body = JSON.stringify(product);
  const etag = etagOf(body);
  if (req.headers['if-none-match'] === etag) {
    res.writeHead(304, { ETag: etag });
    return res.end();
  }
  send(req, res, 200, body, { 'Cache-Control': 'max-age=10, public', ETag: etag });
});

// v2: same resource, new shape. Old clients keep using v1.
route('GET', '/api/v2/products/:id', ({ req, res, params }) => {
  if (Number(params.id) !== 1) return send(req, res, 404, { error: 'Product not found' });
  send(req, res, 200, {
    id: product.id,
    title: product.name,
    cost: product.price,
    currency: 'USD',
  });
});

// PUT replaces the whole resource (idempotent)
route('PUT', '/api/v1/products/:id', ({ req, res, body }) => {
  if (typeof body.name !== 'string' || typeof body.price !== 'number') {
    return send(req, res, 400, { error: 'name (string) and price (number) are required' });
  }
  product = { id: 1, name: body.name, price: body.price };
  send(req, res, 200, product);
});

// POST creates something new every time (not idempotent)
route('POST', '/api/orders', ({ req, res }) => {
  orders.push({ id: orders.length + 1 });
  send(req, res, 201, { totalOrders: orders.length });
});

route('GET', '/api/users/:userId/products/:productId', ({ req, res, params }) =>
  send(req, res, 200, params)
);

// Return any status code on demand
route('GET', '/api/status/:code', ({ req, res, params }) => {
  const code = Number(params.code);
  if (!(code >= 200 && code <= 599)) return send(req, res, 400, { error: 'Use 200-599' });
  if (code === 204 || code === 304) {
    res.writeHead(code);
    return res.end();
  }
  send(req, res, code, { status: code });
});

// 401 without an Authorization header, 200 with one
route('GET', '/api/secure', ({ req, res }) => {
  if (!req.headers.authorization) {
    return send(req, res, 401, { error: 'Missing Authorization header' }, {
      'WWW-Authenticate': 'Bearer',
    });
  }
  send(req, res, 200, { message: 'You are in' });
});

// A large, very compressible response
route('GET', '/api/big', ({ req, res }) =>
  send(req, res, 200, {
    items: Array.from({ length: 500 }, (_, i) => ({
      id: i,
      name: `Item ${i}`,
      description: 'lorem ipsum dolor sit amet '.repeat(3),
    })),
  })
);

// Streaming with Server-Sent Events: five events, 300 ms apart
route('GET', '/api/stream', ({ res }) => {
  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    Connection: 'keep-alive',
  });
  let i = 0;
  const timer = setInterval(() => {
    res.write(`data: token-${++i}\n\n`);
    if (i === 5) {
      clearInterval(timer);
      res.end();
    }
  }, 300);
});

// What the server really saw (the playground shows this). Readable from any origin
// on purpose, so you can still inspect the server side when your CORS setup is broken.
route('GET', '/api/_log', ({ req, res }) =>
  send(req, res, 200, [...requestLog].reverse().slice(0, 15), { 'Access-Control-Allow-Origin': '*' })
);

// ---------- the API server ----------
http
  .createServer(async (req, res) => {
    const url = new URL(req.url, 'http://localhost');
    const origin = req.headers.origin;

    res.on('finish', () => {
      if (url.pathname === '/api/_log') return;
      requestLog.push({
        time: new Date().toISOString().slice(11, 23),
        method: req.method,
        path: url.pathname + url.search,
        status: res.statusCode,
        origin: origin || null,
        rawBytes: res.rawBytes,
        sentBytes: res.sentBytes,
      });
      if (requestLog.length > 50) requestLog.shift();
      console.log(`${req.method} ${url.pathname}${url.search} -> ${res.statusCode}`);
    });

    // CORS: the server only opts an origin in. The browser enforces it.
    res.setHeader('Vary', 'Origin');
    if (origin === ALLOWED_ORIGIN) {
      res.setHeader('Access-Control-Allow-Origin', origin);
      res.setHeader('Access-Control-Expose-Headers', 'ETag, Content-Encoding, Cache-Control');
    }

    // Preflight
    if (req.method === 'OPTIONS') {
      res.writeHead(204, {
        'Access-Control-Allow-Methods': 'GET, POST, PUT, PATCH, DELETE',
        'Access-Control-Allow-Headers': 'Authorization, Content-Type',
        'Access-Control-Max-Age': '86400',
      });
      return res.end();
    }

    const match = routes.find((r) => r.method === req.method && r.regex.test(url.pathname));
    if (!match) return send(req, res, 404, { error: 'Not found' });

    const m = url.pathname.match(match.regex);
    const params = Object.fromEntries(match.keys.map((k, i) => [k, decodeURIComponent(m[i + 1])]));
    try {
      const body = ['POST', 'PUT', 'PATCH'].includes(req.method) ? await readJson(req) : undefined;
      match.handler({ req, res, params, query: url.searchParams, body });
    } catch (err) {
      send(req, res, err.status || 500, { error: err.message });
    }
  })
  .listen(API_PORT, () => console.log(`API   http://localhost:${API_PORT}  (CORS allows ${ALLOWED_ORIGIN})`));

// ---------- a second server for the page, so it is a different origin ----------
const PUBLIC = path.join(__dirname, 'public');
const mime = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.css': 'text/css' };
http
  .createServer((req, res) => {
    const file = req.url.split('?')[0] === '/' ? '/index.html' : req.url.split('?')[0];
    const full = path.join(PUBLIC, path.normalize(file));
    if (!full.startsWith(PUBLIC)) {
      res.writeHead(403);
      return res.end();
    }
    fs.readFile(full, (err, data) => {
      if (err) {
        res.writeHead(404);
        return res.end('Not found');
      }
      res.writeHead(200, { 'Content-Type': mime[path.extname(full)] || 'application/octet-stream' });
      res.end(data);
    });
  })
  .listen(WEB_PORT, () => console.log(`Page  http://localhost:${WEB_PORT}  <- open this`));

It is about 250 lines: a tiny router (method plus pattern maps to a
handler), an in-memory "database", and one handler per concept from the
notes above. Two things to notice. CORS is just a few lines at the top
of the main handler. And every request is also written to a log the
playground reads back, which is how you will see what the server saw,
not only what the browser showed you.

public/index.html

This page is the interactive part. Each card has buttons that fire real
requests at the API. The panel on the right shows what the browser
handed to your code, and the table under it shows what the server
actually saw.

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Backend Lab</title>
<style>
  :root { --bg:#fafaf8; --card:#fff; --ink:#1c1c1a; --mute:#6b6b66; --line:#e4e3de; --ok:#1a7f45; --bad:#b3261e; --accent:#2f5bea; }
  @media (prefers-color-scheme: dark) {
    :root { --bg:#16161a; --card:#1f1f25; --ink:#ececea; --mute:#9a9a94; --line:#33333b; --ok:#4cc37f; --bad:#ff7b72; --accent:#7c9cff; }
  }
  * { box-sizing: border-box; }
  body { margin:0; background:var(--bg); color:var(--ink); font:15px/1.5 system-ui, sans-serif; }
  header { padding:20px 16px 8px; max-width:1100px; margin:0 auto; }
  h1 { margin:0 0 4px; font-size:22px; }
  header p { margin:0; color:var(--mute); }
  main { max-width:1100px; margin:0 auto; padding:8px 16px 40px; display:grid; gap:16px; grid-template-columns:minmax(0,5fr) minmax(0,6fr); }
  @media (max-width:820px) { main { grid-template-columns:1fr; } }
  section { background:var(--card); border:1px solid var(--line); border-radius:10px; padding:12px 14px; margin-bottom:12px; }
  h2 { margin:0 0 2px; font-size:15px; }
  .note { margin:0 0 8px; color:var(--mute); font-size:13px; }
  button { font:inherit; font-size:13px; margin:0 6px 6px 0; padding:5px 10px; border:1px solid var(--line); border-radius:6px; background:var(--bg); color:var(--ink); cursor:pointer; }
  button:hover { border-color:var(--accent); color:var(--accent); }
  .panel-head { display:flex; justify-content:space-between; align-items:center; }
  .panel-head h2 { margin:0; }
  #out .entry { border-top:1px solid var(--line); padding:8px 0; }
  #out .entry:first-child { border-top:0; }
  .ok { color:var(--ok); } .bad { color:var(--bad); } .ms { color:var(--mute); font-size:12px; }
  pre { margin:6px 0 0; padding:8px; background:var(--bg); border-radius:6px; font:12px/1.45 ui-monospace, Menlo, monospace; white-space:pre-wrap; word-break:break-word; }
  table { width:100%; border-collapse:collapse; font:12px ui-monospace, Menlo, monospace; }
  td, th { text-align:left; padding:3px 6px; border-bottom:1px solid var(--line); }
  th { color:var(--mute); font-weight:500; }
</style>
</head>
<body>
<header>
  <h1>Backend Lab</h1>
  <p>This page runs on <b id="me"></b> and calls an API on <b>http://localhost:3001</b>. Different origins, so CORS is real.</p>
</header>
<main>
  <div id="controls"></div>
  <div>
    <section>
      <div class="panel-head"><h2>What the browser showed you</h2><button id="clear">Clear</button></div>
      <div id="out"><p class="note">Click a button on the left.</p></div>
    </section>
    <section>
      <h2>What the server really saw</h2>
      <p class="note">Browsers hide some things (304s, preflights). The server does not.</p>
      <table><thead><tr><th>time</th><th>request</th><th>status</th><th>bytes</th></tr></thead><tbody id="log"></tbody></table>
    </section>
  </div>
</main>
<script>
const API = 'http://localhost:3001';
const out = document.getElementById('out');
document.getElementById('me').textContent = location.origin;
const esc = (s) => s.replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[c]));
const json = (method, body) => ({ method, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });

function addEntry(html) {
  if (out.querySelector('.note')) out.innerHTML = '';
  const el = document.createElement('div');
  el.className = 'entry';
  el.innerHTML = html;
  out.prepend(el);
  return el;
}

async function call(label, path, opts = {}) {
  const t0 = performance.now();
  try {
    const res = await fetch(API + path, opts);
    const text = await res.text();
    const ms = Math.round(performance.now() - t0);
    const hdrs = ['etag', 'cache-control', 'content-encoding']
      .filter((h) => res.headers.get(h))
      .map((h) => `${h}: ${res.headers.get(h)}`)
      .join('\n');
    addEntry(`<b class="${res.ok ? 'ok' : 'bad'}">${res.status}</b> ${esc(label)} <span class="ms">${ms} ms</span>` +
      `<pre>${esc((hdrs ? hdrs + '\n\n' : '') + (text.slice(0, 300) || '(empty body)'))}</pre>`);
  } catch {
    addEntry(`<b class="bad">blocked</b> ${esc(label)}<pre>The browser refused to hand this response to your code, usually because of CORS. ` +
      `Open DevTools > Console for the exact reason, then check "What the server really saw". A simple request still reaches the server; a preflighted one stops at the OPTIONS.</pre>`);
  }
  refreshLog();
}

async function stream() {
  const t0 = performance.now();
  const el = addEntry(`<b class="ok">stream</b> GET /api/stream<pre></pre>`);
  const pre = el.querySelector('pre');
  const res = await fetch(API + '/api/stream');
  const reader = res.body.getReader();
  const dec = new TextDecoder();
  for (;;) {
    const { done, value } = await reader.read();
    if (done) break;
    pre.textContent += `+${Math.round(performance.now() - t0)} ms  ${dec.decode(value).trim()}\n`;
  }
  refreshLog();
}

async function refreshLog() {
  try {
    const rows = await (await fetch(API + '/api/_log', { cache: 'no-store' })).json();
    document.getElementById('log').innerHTML = rows.map((r) => {
      const bytes = r.rawBytes == null ? '' : r.rawBytes === r.sentBytes ? r.sentBytes : `${r.rawBytes} → ${r.sentBytes}`;
      return `<tr><td>${r.time}</td><td>${r.method} ${esc(r.path)}</td><td>${r.status}</td><td>${bytes}</td></tr>`;
    }).join('');
  } catch { /* server not reachable */ }
}

const groups = [
  { title: '1 · Routing and versioning', note: 'Static, path params, query params, nested, and v1 vs v2 of one resource.', items: [
    ['GET /api/v1/products/1', '/api/v1/products/1'],
    ['GET /api/v2/products/1', '/api/v2/products/1'],
    ['GET /api/v1/products?page=2&limit=5', '/api/v1/products?page=2&limit=5'],
    ['GET /api/users/7/products/1', '/api/users/7/products/1'],
  ]},
  { title: '2 · Status codes', note: 'The server returns whatever code you click.', items:
    [200, 400, 401, 403, 404, 409, 429, 500, 503].map((c) => [`${c}`, `/api/status/${c}`]) },
  { title: '3 · CORS and preflight', note: 'Open DevTools > Network. The last two send an OPTIONS request first.', items: [
    ['Simple GET (no preflight)', '/api/v1/products/1'],
    ['GET without Authorization (401)', '/api/secure'],
    ['GET + Authorization (preflight)', '/api/secure', { headers: { Authorization: 'Bearer demo' } }],
    ['PUT with JSON body (preflight)', '/api/v1/products/1', json('PUT', { name: 'iPhone', price: 600 })],
  ]},
  { title: '4 · Caching', note: 'fetch hides 304s. Watch the server table for the real status.', items: [
    ['GET product (ETag + max-age=10)', '/api/v1/products/1'],
    ['GET, force revalidation', '/api/v1/products/1', { cache: 'no-cache' }],
    ['PUT price to 700', '/api/v1/products/1', json('PUT', { name: 'iPhone', price: 700 })],
    ['PUT price back to 500', '/api/v1/products/1', json('PUT', { name: 'iPhone', price: 500 })],
  ]},
  { title: '5 · Idempotency', note: 'Click each one three times and compare.', items: [
    ['PUT price 600 (idempotent)', '/api/v1/products/1', json('PUT', { name: 'iPhone', price: 600 })],
    ['POST /api/orders (not idempotent)', '/api/orders', { method: 'POST' }],
  ]},
  { title: '6 · Compression', note: 'Check the bytes column: raw size → size on the wire.', items: [
    ['GET /api/big', '/api/big'],
  ]},
];

const controls = document.getElementById('controls');
for (const g of groups) {
  const s = document.createElement('section');
  s.innerHTML = `<h2>${g.title}</h2><p class="note">${g.note}</p>`;
  for (const [label, path, opts] of g.items) {
    const b = document.createElement('button');
    b.textContent = label;
    b.onclick = () => call(`${opts?.method || 'GET'} ${path}`, path, opts);
    s.appendChild(b);
  }
  controls.appendChild(s);
}
const s7 = document.createElement('section');
s7.innerHTML = '<h2>7 · Streaming</h2><p class="note">One open connection, five events, no Content-Length.</p>';
const sb = document.createElement('button');
sb.textContent = 'GET /api/stream';
sb.onclick = stream;
s7.appendChild(sb);
controls.appendChild(s7);

document.getElementById('clear').onclick = () => (out.innerHTML = '<p class="note">Click a button on the left.</p>');
refreshLog();
</script>
</body>
</html>

That's the whole setup. Start the server, open the page, and you have a
lab bench for everything below.

Run the experiments

Start the lab with Node.js 18 or newer:

node server.js

Open http://localhost:5173, then open your browser's Developer Tools
and select Network. The page runs on port 5173; the API runs on
port 3001. Different ports mean different origins, so the browser's
CORS behaviour is part of the experiment.

For each test, make a prediction before clicking the button. Then
compare three things:

The browser panel: what fetch returned to JavaScript.
The server log: which requests actually reached the API and which status codes it returned.
The Network panel: request headers, response headers, preflight requests, transferred bytes, and timing.

That prediction-and-check loop is the point of the lab. Don't just
confirm that a request works; try to explain why it behaved that way.

Experiment 1 --- A CORS error does not always mean the request never arrived

Click the simple GET request.
In the server log, confirm that the request reached the API.
Restart the server with an origin that does not match the page's
origin:
```
ALLOWED_ORIGIN=http://example.com node server.js
```
Reload the page and click the simple GET again.

The browser should block the page's JavaScript from reading the response
because the server did not allow the page's origin. The server log can
still show a 200 response. This is the first key distinction: a
browser CORS error describes what the browser permits the page to read;
it does not necessarily describe whether the server received a
request.

Now click the PUT button with a JSON body. Because this request
requires preflight, the browser first sends OPTIONS. With the origin
misconfigured, the preflight fails and the browser should not send the
actual PUT. Check the log rather than guessing from the error message.

Restore the default configuration before continuing.

Experiment 2 --- Inspect the preflight

Click the button that sends a PUT with JSON, then inspect the Network
panel. Look for an OPTIONS request before the PUT.

A preflight response can include headers such as:

Access-Control-Allow-Origin: http://localhost:5173
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 86400

These headers describe which origin, methods, and request headers the
browser is permitted to use. Access-Control-Max-Age lets the browser
cache the preflight result for the stated period, subject to browser
limits and the rest of the CORS configuration.

Try the GET with an Authorization header too. Then compare it with
the simple GET. The important question is not merely "Did the request
succeed?" but "Which requests did the browser send before the API
handler ran?"

Experiment 3 --- Watch caching change the request

Click GET product.
Click GET, force revalidation.
Compare the browser panel with the server log.
Change the product price with PUT, then revalidate again.

The product endpoint returns an ETag and a Cache-Control header. The
first request should return a full 200 response. When you force
revalidation while the representation is unchanged, the server can
answer 304 Not Modified; the browser can then reuse the body it
already has. After the product changes, the ETag should change and the
server should send the updated representation.

To inspect the conditional request outside the browser, first make a
request and copy the actual ETag value from its response:

curl -i http://localhost:3001/api/v1/products/1

Then use that exact value:

curl -i http://localhost:3001/api/v1/products/1 \
  -H 'If-None-Match: "PASTE_THE_ETAG_HERE"'

Do not assume the ETag is a permanent constant. It is derived from the
current representation, so changing the product changes the tag.

One more detail: a fresh cached response can be reused without a request
reaching the server at all. A 304 means a request did reach the
server and the server told the client to reuse its stored
representation. Those are different cache paths.

Experiment 4 --- Idempotency is about state

Click PUT price 600 several times. Then click POST /api/orders
several times.

The PUT replaces the product with the same supplied representation, so
repeating it leaves the product in the same state. The POST handler
adds another order each time, so the order count grows.

The distinction is about the effect on server state, not whether the
response bytes or status code are identical. For an extra challenge,
implement DELETE /api/v1/products/1 so the first request removes the
product and returns 204. Decide what the second request should return.
It could return 404, for example, while the resource remains deleted;
that can still be idempotent because the final state is unchanged.

Experiment 5 --- Measure compression and observe streaming

Compression: click GET /api/big and compare the raw and
transferred byte counts in the server log. The endpoint returns
repetitive JSON, which is a good candidate for gzip compression. If you
measure it with curl, use the same URL and compare the response with
and without an Accept-Encoding: gzip header:

curl -s http://localhost:3001/api/big | wc -c
curl -s -H 'Accept-Encoding: gzip' http://localhost:3001/api/big | wc -c

Exact byte counts can vary if the payload or code changes. Also,
command-line clients and browsers may display compressed responses
differently, so make sure you understand whether the tool is showing
compressed transfer bytes or the decompressed body.

Streaming: click GET /api/stream. The page should display five
events arriving over one connection, roughly 300 milliseconds apart.
Instead of waiting for one complete JSON body, the client reads chunks
as they arrive. Timing will vary across machines and browsers; focus on
the sequence of events and the fact that the connection remains open
while the server sends them.

What these experiments changed in my mental model

A browser error is not always a server error. The browser, network, and server are separate places where a request can fail or be blocked.
CORS is a browser-enforced sharing policy, not an API authentication system. Direct clients do not automatically follow browser CORS rules.
The browser's view is not the whole story. Server logs reveal requests and status codes that may not be obvious from the fetch result alone.
Caching can save a network request entirely. A fresh cache entry and a conditional 304 response are different paths.
Idempotency describes the intended state change. It is especially important when a client retries after an uncertain network failure.
Headers affect behaviour. They communicate cache rules, representation formats, compression, and browser permissions.
Measurements need context. Compression ratios and timings are observations from a particular payload and environment, not universal performance guarantees.

The biggest lesson for me is that backend debugging gets easier when I
stop looking only at the final JSON. The request method, headers,
status, timing, cache behaviour, and server logs all help explain what
happened.

Try this yourself

Before moving on, pick one of these small extensions:

Add a DELETE endpoint and test repeated requests.
Change the allowed origin and predict which requests will reach the API.
Change the product twice and observe how its ETag changes.
Add a query parameter for filtering the product list.
Modify the streaming endpoint to send ten events instead of five.

For each change, write down what you expect to happen before testing it.
That habit is more valuable than memorising a list of HTTP headers.