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

The article explains that Node.js includes a built-in HTTP module enabling developers to create servers, handle requests and responses, and manage routing without external packages. It provides practical examples of creating a basic server, setting response headers, accessing request headers, and parsing URLs and query strings. The guide emphasizes that mastering this module is a foundational skill for backend developers building REST APIs or serving web content.

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. js const http = require 'http' ; If you are using ES Modules: python import http from 'http'; Creating Your First HTTP Server Let’s build a simple Node.js server. js 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 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 js 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: js 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. js 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. js 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: js 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 js 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. js 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. 🚀