Mastering Node.js HTTP Module: Build Servers, REST APIs, and Handle Requests

Introduction to the HTTP Module

Modern web applications rely heavily on communication between clients and servers. Whether you are building a REST API, handling browser requests, or serving files, understanding the HTTP module in Node.js is a foundational skill every backend developer should master.

Node.js provides a built-in HTTP module that allows developers to create servers, manage requests and responses, handle routing, and even stream large amounts of data efficiently — all without installing external packages.

In this article, we’ll explore the Node.js HTTP module in depth with practical examples, explanations, best practices, and real-world usage scenarios.

What is HTTP?

HTTP stands for:

HyperText Transfer Protocol

It is the protocol used for communication between:

Browsers and web servers
Frontend and backend applications
APIs and clients

When you visit a website:

Your browser sends an HTTP request
The server processes it
The server sends back an HTTP response

Key Features:

Create HTTP servers to handle requests and send responses
Make HTTP requests to other servers
Handle different HTTP methods (GET, POST, PUT, DELETE, etc.)
Work with request and response headers
Handle streaming data for large payloads

Importing the HTTP Module

Node.js uses the require() function to import modules.

const http = require('http');

If you are using ES Modules:

import http from 'http';

Creating Your First HTTP Server

Let’s build a simple Node.js server.

const http = require('http');

const server = http.createServer((req, res) => {

  res.writeHead(200, {
    'Content-Type': 'text/plain'
  });

  res.end('Hello, World!');
});

server.listen(3000, () => {
  console.log('Server running on port 3000');
});

Understanding the Server Code

http.createServer()

Creates an HTTP server.

Parameters

req → Request object
res → Response object

res.writeHead()

Used to set:

Status code
Headers

res.writeHead(200, {
  'Content-Type': 'text/plain'
});

res.end()

Sends the response and closes the connection.

res.end('Hello World');

server.listen()

Starts the server.

server.listen(3000);

Running the Server

Save the code in a file named server.js
Run the server using Node.js:

node server.js

Visit http://localhost:3000 in your browser to see the response.

Working with HTTP Headers

HTTP headers let you send additional information with your response.
The res.writeHead() method is used to set the status code and response headers.

Setting Response Headers

const http = require('http');

const server = http.createServer((req, res) => {
  // Set status code and multiple headers
  res.writeHead(200, {
    'Content-Type': 'text/html',
    'X-Powered-By': 'Node.js',
    'Cache-Control': 'no-cache, no-store, must-revalidate',
    'Set-Cookie': 'sessionid=abc123; HttpOnly'
  });

  res.end('<h1>Hello, World!</h1>');
});

server.listen(3000, () => {
  console.log('Server running at http://localhost:3000/');
});

Common HTTP Status Codes

Code	Message	Description
200	OK	Standard response for successful HTTP requests
201	Created	Request has been fulfilled and new resource created
301	Moved Permanently	Resource has been moved to a new URL
400	Bad Request	Server cannot process the request due to client error
401	Unauthorized	Authentication is required
403	Forbidden	Server refuses to authorize the request
404	Not Found	Requested resource could not be found
500	Internal Server Error	Unexpected condition was encountered

Common Response Headers

Content-Type: Specifies the media type of the content (e.g., text/html, application/json)
Content-Length: The length of the response body in bytes
Location: Used in redirects (with 3xx status codes)
Set-Cookie: Sets HTTP cookies on the client
Cache-Control: Directives for caching mechanisms
Access-Control-Allow-Origin: For CORS support

Reading Request Headers

You can access request headers using the req.headers object:

const http = require('http');

const server = http.createServer((req, res) => {
  // Log all request headers
  console.log('Request Headers:', req.headers);

  // Get specific headers (case-insensitive)
  const userAgent = req.headers['user-agent'];
  const acceptLanguage = req.headers['accept-language'];

  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end(`User-Agent: ${userAgent}\nAccept-Language: ${acceptLanguage}`);
});

server.listen(3000);

// User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36
// Accept-Language: en-US,en;q=0.9,nb;q=0.8,da;q=0.7,no;q=0.6

Working with URLs and Query Strings

Node.js provides built-in modules for working with URLs and query strings, making it easy to parse URL components and query parameters.

Accessing the Request URL

The req.url property contains the URL string that was requested, including any query parameters.

This is part of the http.IncomingMessage object.

const http = require('http');

const server = http.createServer((req, res) => {
  // Get the URL and HTTP method
  const { url, method } = req;

  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end(`You made a ${method} request to ${url}`);
});

server.listen(3000, () => {
  console.log('Server running at http://localhost:3000/');
});

// You made a GET request to /

Parsing URLs with the URL Module

The url module provides utilities for URL resolution and parsing.

It can parse a URL string into a URL object with properties for each part of the URL.

const http = require('http');
const url = require('url');

const server = http.createServer((req, res) => {
  // Parse the URL
  const parsedUrl = url.parse(req.url, true);

  // Get different parts of the URL
  const pathname = parsedUrl.pathname; // The path without query string
  const query = parsedUrl.query; // The query string as an object

  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    pathname,
    query,
    fullUrl: req.url
  }, null, 2));
});

server.listen(3000);

Example Requests and Responses

For the following request:

GET /products?category=electronics&sort=price&page=2 HTTP/1.1

The server would respond with:

{
"pathname": "/products",
"query": {
"category": "electronics",
"sort": "price",
"page": "2"
},
"fullUrl": "/products?category=electronics&sort=price&page=2"
}

Working with Query Strings

For more advanced query string handling, you can use the querystring module:

const http = require('http');
const { URL } = require('url');
const querystring = require('querystring');

const server = http.createServer((req, res) => {
  // Using the newer URL API (Node.js 10+)
  const baseURL = 'http://' + req.headers.host + '/';   const parsedUrl = new URL(req.url, baseURL);

  // Get query parameters
  const params = Object.fromEntries(parsedUrl.searchParams);

  // Example of building a query string
  const queryObj = {
    name: 'John Doe',
    age: 30,
    interests: ['programming', 'music']
  };
  const queryStr = querystring.stringify(queryObj);

  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    path: parsedUrl.pathname,
    params,
    exampleQueryString: queryStr
  }, null, 2));
});

server.listen(3000);

{
  "path": "/",
  "params": {},
  "exampleQueryString": "name=John%20Doe&age=30&interests=programming&interests=music"
}

Common URL Parsing Methods

url.parse(urlString, [parseQueryString], [slashesDenoteHost]): Parse a URL string into an object
url.format(urlObject): Format a URL object into a URL string
url.resolve(from, to): Resolve a target URL relative to a base URL
new URL(input, [base]): The WHATWG URL API (recommended for new code)
querystring.parse(str, [sep], [eq], [options]): Parse a query string into an object
querystring.stringify(obj, [sep], [eq], [options]): Stringify an object into a query string

Handling Different HTTP Methods

RESTful APIs commonly use different HTTP methods (GET, POST, PUT, DELETE, etc.) to perform different operations on resources.

Here's how to handle different HTTP methods in a Node.js HTTP server:

Example: Handling Multiple HTTP Methods

const http = require('http');
const { URL } = require('url');

// In-memory data store (for demonstration)
let todos = [
  { id: 1, task: 'Learn Node.js', completed: false },
  { id: 2, task: 'Build an API', completed: false }
];

const server = http.createServer((req, res) => {
  const { method, url } = req;
  const parsedUrl = new URL(url, `http://${req.headers.host}`);
  const pathname = parsedUrl.pathname;

  // Set CORS headers (for development)
  res.setHeader('Access-Control-Allow-Origin', '*');
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');

  // Handle preflight requests
  if (method === 'OPTIONS') {
    res.writeHead(204);
    res.end();
    return;
  }

  // Route: GET /todos
  if (method === 'GET' && pathname === '/todos') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify(todos));
  }
  // Route: POST /todos
  else if (method === 'POST' && pathname === '/todos') {
    let body = '';
    req.on('data', chunk => {
      body += chunk.toString();
    });

    req.on('end', () => {
      try {
        const newTodo = JSON.parse(body);
        newTodo.id = todos.length > 0 ? Math.max(...todos.map(t => t.id)) + 1 : 1;
        todos.push(newTodo);
        res.writeHead(201, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify(newTodo));
      } catch (error) {
        res.writeHead(400, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({ error: 'Invalid JSON' }));
      }
    });
  }

  // Route: PUT /todos/:id
  else if (method === 'PUT' && pathname.startsWith('/todos/')) {
    const id = parseInt(pathname.split('/')[2]);
    let body = '';

    req.on('data', chunk => {
      body += chunk.toString();
    });

    req.on('end', () => {
      try {
        const updatedTodo = JSON.parse(body);
        const index = todos.findIndex(t => t.id === id);

        if (index === -1) {
          res.writeHead(404, { 'Content-Type': 'application/json' });
          res.end(JSON.stringify({ error: 'Todo not found' }));
        } else {
          todos[index] = { ...todos[index], ...updatedTodo };
          res.writeHead(200, { 'Content-Type': 'application/json' });
          res.end(JSON.stringify(todos[index]));
        }
      } catch (error) {
        res.writeHead(400, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({ error: 'Invalid JSON' }));
      }
    });
  }

  // Route: DELETE /todos/:id
  else if (method === 'DELETE' && pathname.startsWith('/todos/')) {
    const id = parseInt(pathname.split('/')[2]);
    const index = todos.findIndex(t => t.id === id);

    if (index === -1) {
      res.writeHead(404, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ error: 'Todo not found' }));
    } else {
      todos = todos.filter(t => t.id !== id);
      res.writeHead(204);
      res.end();
    }
  }

  // 404 Not Found
  else {
    res.writeHead(404, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ error: 'Not Found' }));
  }
});

const PORT = 3000;
server.listen(PORT, () => {
  console.log(`Server running at http://localhost:${PORT}/`);
});

Testing the API with cURL

You can test this API using cURL commands:

# 1. Get all todos
curl http://localhost:3000/todos

# 2. Create a new todo
curl -X POST http://localhost:3000/todos \
-H "Content-Type: application/json" \
-d '{"task":"New Task","completed":false}'

# 3. Update a todo
curl -X PUT http://localhost:3000/todos/1 \
-H "Content-Type: application/json" \
-d '{"completed":true}'

# 4. Delete a todo
curl -X DELETE http://localhost:3000/todos/1

Best Practices for HTTP Methods

GET: Retrieve a resource or collection of resources (should be idempotent)
POST: Create a new resource (not idempotent)
PUT: Update an existing resource or create it if it doesn't exist (idempotent)
PATCH: Partially update a resource
DELETE: Remove a resource (idempotent)
HEAD: Same as GET but without the response body
OPTIONS: Describe the communication options for the target resource

Error Handling

Always include proper error handling and appropriate HTTP status codes:

200 OK - Successful GET/PUT/PATCH
201 Created - Successful resource creation
204 No Content - Successful DELETE
400 Bad Request - Invalid request data
401 Unauthorized - Authentication required
403 Forbidden - Not enough permissions
404 Not Found - Resource doesn't exist
500 Internal Server Error - Server-side error

Streaming Responses

Node.js streams are powerful for handling large amounts of data efficiently. The HTTP module works well with streams for both reading request bodies and writing responses.

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

const server = http.createServer((req, res) => {
  // Get the file path from the URL
  const filePath = path.join(__dirname, req.url);

  // Check if file exists
  fs.access(filePath, fs.constants.F_OK, (err) => {
    if (err) {
      res.statusCode = 404;
      res.end('File not found');
      return;
    }

    // Get file stats
    fs.stat(filePath, (err, stats) => {
      if (err) {
        res.statusCode = 500;
        res.end('Server error');
        return;
      }

      // Set appropriate headers
      res.setHeader('Content-Length', stats.size);
      res.setHeader('Content-Type', 'application/octet-stream');

      // Create read stream and pipe to response
      const stream = fs.createReadStream(filePath);

      // Handle errors
      stream.on('error', (err) => {
        console.error('Error reading file:', err);
        if (!res.headersSent) {
          res.statusCode = 500;
          res.end('Error reading file');
        }
      });

      // Pipe the file to the response
      stream.pipe(res);
    });
  });
});

const PORT = 3000;
server.listen(PORT, () => {
  console.log(`File server running at http://localhost:${PORT}/`);
});

Benefits of Streaming

Memory Efficiency: Processes data in chunks instead of loading everything into memory
Faster Time to First Byte: Starts sending data as soon as it's available
Backpressure Handling: Automatically handles slow clients by pausing the read stream

Common Use Cases for Streaming

File uploads/downloads
Real-time data processing
Proxying requests
Video/audio streaming
Log processing

Final Thoughts

The Node.js HTTP module is one of the most important building blocks in backend development. While frameworks like Express simplify development, understanding the core HTTP module gives you deeper insight into how web servers, APIs, and request-response cycles actually work.

Mastering this module will help you:

Build scalable backend systems
Understand REST APIs deeply
Improve debugging skills
Handle streams efficiently
Become a stronger Node.js developer

If you're serious about backend engineering, learning the HTTP module thoroughly is absolutely worth your time. 🚀

推荐订阅源

DEV Community