Parse HTTP Requests in Express

In web development, parsing requests refers to the process of analyzing and converting the data contained in the message body of incoming requests into a more usable format — usually strings or JSON — that the server can understand and work with.

Parsing is usually done according to the value of the request's HTTP Content-Type header that contains a string called a media type (formerly known as MIME type) that describes the format of the message body, allowing the server to process the data sent by the client appropriately.

To do so, the Express framework provides built-in body-parsing middleware functions that allow developers to parse to parse the main 4 media types:

const { text, json, urlencoded, raw } = require('express');

Whenever used, these middlewares will try to parse the payload of the incoming request based on their Content-Type header and add a new body property to the request object (i.e. req.body).

This body property will either be defined as:

• An object containing the parsed values.
• An empty object in the case something went wrong, like for example a malformed message body or the use of a parsing method that doesn't match the Content-Type header.

The text middleware

The text() middleware is used to parse incoming requests whose Content-Type header is set to text/plain.

This media type is commonly used for transmitting textual data without any special formatting or structure, that doesn't require any specific processing, like ASCII characters and Unicode characters.

Example

In this example, the POST /text route uses the text() middleware to assign a string to the req.body property:

const express = require('express');

const app = express();

app.post('/text', express.text(), (req, res) => {
  console.log(req.body);
  res.sendStatus(200);
});

app.listen(3000);

When sending this request to the server:

$ curl -X POST -H 'Content-Type: text/plain' -d 'John Doe' 127.0.0.1:3000/text

It will produce this output:

John Doe

The json middleware

The json() middleware is used to parse incoming requests whose Content-Type header is set to application/json.

This media type is commonly used for transmitting structured data in the JSON format, which is easy for humans to read and write, and easy for machines to parse and generate.

Example

In this example, the POST /json route uses the json() middleware to convert a JSON string into a JSON object:

const express = require('express');
const app = express();

app.post('/json', express.json(), (req, res) => {
  console.log(req.body);
  res.sendStatus(200);
});

app.listen(3000);

When sending this request to the server:

$ curl -X POST -H 'Content-Type: application/json' -d '{"name":"John Doe"}' 127.0.0.1:3000/json

It will produce this output:

{ name: 'John Doe' }

The urlencoded middleware

The urlencoded middleware is used to parse incoming requests whose Content-Type header is set to application/x-www-form-urlencoded.

This media type is commonly used for transmitting url-encoded (or percent-encoded) data from HTML forms to web servers.

Example

In this example, the POST /urlencoded route uses the urlencoded() middleware to convert a URL-encoded string into a JSON object:

const express = require('express');
const app = express();

app.post('/urlencoded', express.urlencoded(), (req, res) => {
  console.log(req.body);
  res.sendStatus(200);
});

app.listen(3000);

When sending this request to the server:

$ curl -X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'email=johndoe%40mail.com&password=h3ll0W%40rld' \
127.0.0.1:3000/urlencoded

It will produce this output:

{ email: 'johndoe@mail.com', password: 'h3ll0W@rld' }

The raw middleware

The raw middleware is used to parse incoming requests whose Content-Type header is set to application/octet-stream.

This media type is commonly used for transmitting any kind of binary data, such as images, audio files, video files, etc, or data whose type doesn't fit into a more specific media type.

Example

In this example, the POST /raw route uses the raw() middleware to convert raw bytes into a Buffer object:

const express = require('express');
const app = express();

app.post('/raw', express.raw(), (req, res) => {
  console.log(req.body);
  res.sendStatus(200);
});

app.listen(3000);

When sending this request to the server:

$ curl -X POST \
-H 'Content-Type: application/octet-stream' \
--data-binary ~/Downloads/invoice.pdf \
127.0.0.1:3000/raw

It will produce this output:

<Buffer 2f 55 20 65 51 20 2f 51 6c 1f 64 6f 20 61 5e 1f 2f 44 6f 77 5e 6c 6f 61 64 ... 4 more bytes>

Summary

Here's a summary of what you've learned in this lesson:

• Parsing requests refers to the process of converting the data contained in the message body of a request into a more usable format.
• The Content-Type header is used to indicate the media type of the request.
• The express.text() middleware is used to parse the text/plain media type into a string.
• The express.json() middleware is used to parse the application/json media type into a JSON object.
• The express.urlencoded() middleware is used to parse the application/x-www-form-urlencoded media type into a JSON object.
• The express.raw() middleware is used to parse the application/octet-stream media type into a Buffer object.