HTTP Module - Handling POST Requests

HTTP Module - Handling POST Requests in Node.js

Introduction

Node.js, with its built-in http module, provides robust tools for handling different types of HTTP requests, including the POST method. POST requests are typically used to submit data to a server, such as form inputs, JSON payloads, or file uploads. Handling POST requests correctly is essential in building web applications, APIs, or backend services.

In this document, we’ll cover how to handle POST requests using Node.js’ core http module without any third-party libraries. We will discuss reading request data, parsing different content types, responding to the client, and implementing real-world examples like handling JSON and form data.

What is a POST Request?

The POST method is one of the most commonly used HTTP methods. It is used to send data to the server to create or update resources. Unlike GET, which appends data to the URL, POST includes the data in the body of the request.

Key Characteristics of POST

• Data is sent in the request body
• Common content types: application/json, application/x-www-form-urlencoded, multipart/form-data
• Used in login forms, data submissions, RESTful APIs, etc.

Setting Up a Basic HTTP Server

Start by creating a basic HTTP server in Node.js.

const http = require('http');

const server = http.createServer((req, res) => {
    // Handle requests here
});

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

Detecting a POST Request

We check the HTTP method and the request URL.

if (req.method === 'POST' && req.url === '/submit') {
    // Handle POST data
}

Receiving Data from a POST Request

Data sent in POST requests comes in as a stream. We need to collect the data chunks and then process them.

Step-by-step Process

1. Listen to the 'data' event to collect chunks
2. Listen to the 'end' event to process the complete data

Example: Basic POST Handler

const http = require('http');

const server = http.createServer((req, res) => {
    if (req.method === 'POST' && req.url === '/submit') {
        let body = '';

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

        req.on('end', () => {
            console.log('Received data:', body);
            res.writeHead(200, { 'Content-Type': 'text/plain' });
            res.end('Data received successfully');
        });
    } else {
        res.writeHead(404);
        res.end('Not Found');
    }
});

server.listen(3000);

Handling application/json Content-Type

Clients often send data in JSON format. We can parse the JSON string into an object.

if (req.headers['content-type'] === 'application/json') {
    req.on('data', chunk => {
        body += chunk.toString();
    });

    req.on('end', () => {
        const parsed = JSON.parse(body);
        console.log(parsed);
    });
}

Complete Example with JSON

const http = require('http');

const server = http.createServer((req, res) => {
    if (req.method === 'POST' && req.url === '/json') {
        let body = '';

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

        req.on('end', () => {
            try {
                const data = JSON.parse(body);
                console.log('JSON received:', data);

                res.writeHead(200, { 'Content-Type': 'application/json' });
                res.end(JSON.stringify({ message: 'JSON received', data }));
            } catch (err) {
                res.writeHead(400, { 'Content-Type': 'application/json' });
                res.end(JSON.stringify({ error: 'Invalid JSON' }));
            }
        });
    } else {
        res.writeHead(404);
        res.end('Not Found');
    }
});

server.listen(3000);

Handling application/x-www-form-urlencoded

This is the default encoding type for HTML forms. The data format is like name=John&age=30.

const querystring = require('querystring');

const server = http.createServer((req, res) => {
    if (req.method === 'POST' && req.url === '/form') {
        let body = '';

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

        req.on('end', () => {
            const formData = querystring.parse(body);
            console.log('Form data:', formData);

            res.writeHead(200, { 'Content-Type': 'application/json' });
            res.end(JSON.stringify(formData));
        });
    }
});

server.listen(3000);

Sending POST Requests (Client Side)

Using fetch API

fetch('http://localhost:3000/json', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name: 'John', age: 25 })
});

Using HTML Form

<form method="POST" action="/form">
    <input type="text" name="name" />
    <input type="number" name="age" />
    <button type="submit">Submit</button>
</form>

Handling Large POST Requests

For large POST payloads, it is a good practice to limit the size and handle memory safely.

let body = '';
const MAX_SIZE = 1e6;

req.on('data', chunk => {
    body += chunk;
    if (body.length > MAX_SIZE) {
        req.connection.destroy();
    }
});

Handling File Uploads

Handling multipart/form-data (used for file uploads) is complex and usually requires a third-party module like formidable or multer. However, it is possible to do it manually by parsing the incoming stream.

Example with formidable:

const formidable = require('formidable');

http.createServer((req, res) => {
    if (req.method === 'POST' && req.url === '/upload') {
        const form = new formidable.IncomingForm();

        form.parse(req, (err, fields, files) => {
            if (err) {
                res.writeHead(500);
                return res.end('Error parsing form');
            }

            res.writeHead(200, { 'Content-Type': 'application/json' });
            res.end(JSON.stringify({ fields, files }));
        });
    }
}).listen(3000);

Using Async/Await with POST Requests

async function collectData(req) {
    return new Promise((resolve, reject) => {
        let body = '';

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

        req.on('end', () => {
            resolve(body);
        });

        req.on('error', err => {
            reject(err);
        });
    });
}

const server = http.createServer(async (req, res) => {
    if (req.method === 'POST' && req.url === '/async') {
        try {
            const rawData = await collectData(req);
            const parsedData = JSON.parse(rawData);

            res.writeHead(200, { 'Content-Type': 'application/json' });
            res.end(JSON.stringify({ received: parsedData }));
        } catch (err) {
            res.writeHead(400);
            res.end('Error parsing JSON');
        }
    }
});

server.listen(3000);

Error Handling in POST Requests

• Catch JSON parse errors
• Reject oversized bodies
• Validate required fields
• Return proper HTTP status codes (400, 500)

try {
    const data = JSON.parse(body);
    if (!data.name) throw new Error("Missing name");

    res.writeHead(200);
    res.end("OK");
} catch (err) {
    res.writeHead(400);
    res.end("Bad Request: " + err.message);
}

Best Practices

• Always validate incoming data
• Use streaming when handling large bodies
• Handle errors gracefully
• Use appropriate content-type headers
• Limit input size to prevent abuse

Handling POST requests is a vital part of building web servers in Node.js. The built-in http module allows us to handle POST data efficiently by streaming data chunks and processing the final payload. Whether working with JSON, URL-encoded form data, or files, understanding how to parse and validate this information is essential for building secure and reliable backend applications.

While third-party libraries like Express simplify this process, learning how to manage POST requests manually deepens your understanding of Node.js internals and enhances your debugging skills. Mastery of the http module gives you control over how requests are received, interpreted, and responded to.

This guide has covered everything from setting up a basic POST route using Node.js’ native http module to parsing different types of data and implementing real-world handling logic. By learning these techniques, you're better equipped to handle complex server-side logic in a Node.js application with or without external frameworks.