Parse API request bodies
API endpoints receiving application/json payloads need parsed objects available to route handlers.
Express.js · Function
express.json
Creates Express middleware for parsing JSON request bodies. Matching parsed data is placed on req.body, with configurable size, media-type, inflation, and parsing behavior.
- Since
- 4.16.0
How it works
Call express.json() to create middleware that parses request bodies whose Content-Type matches its configured type, then places the parsed value on req.body. It accepts Unicode input and automatically inflates gzip or deflate content; requests without a body, with a nonmatching type, or with a parsing error leave req.body as an empty object.
Syntax
express.json([options])Parameters
| Name | Type | Description |
|---|---|---|
options | Object | undefined | Optional parser configuration. Supported settings include inflate, limit, reviver, strict, type, and verify. |
Returns
Middleware that parses matching JSON request bodies and populates req.body with the parsed data.
Key points
- express.json is supplied by Express itself, so an additional body-parser installation is not required for this parser.
- Its purpose is request-body parsing rather than response serialization or general-purpose content negotiation.
- Unicode request bodies are accepted, and gzip or deflate content is decompressed automatically by default.
- The default maximum body size is 100kb; limit can be a number of bytes or a human-readable size string.
- A reviver function can transform or filter values during JSON parsing using the same semantics as JSON.parse.
- The type option selects which media types are eligible for JSON parsing and can be configured beyond application/json.
Common mistakes
- Only matching Content-Type requests are parsed; sending JSON with an unexpected media type will not populate the body with parsed data.
- Do not assume req.body always contains parsed input: it can be an empty object when there is no body, the type does not match, or parsing fails.
- Setting inflate to false rejects compressed request bodies instead of transparently decompressing them.
Example: Parse JSON request bodies
const express = require('express');
const app = express();
app.use(express.json({ limit: '1mb' }));
app.post('/profile', (req, res) => {
res.json({ received: req.body });
});
app.listen(3000);The middleware parses matching JSON request bodies before the route handler, making the parsed value available as req.body.
When to use it
Enforce request-size limits
Endpoints need a smaller or larger maximum body size than the default.
Customize accepted JSON input
Applications accept vendor-specific JSON media types or need custom JSON.parse transformations.
Interview questions
QWhat does express.json() do?
express.json() returns middleware that parses JSON request bodies and assigns the parsed result to req.body. By default, it considers requests whose Content-Type is application/json.
Follow-up: How can parsing be restricted to another media type? Pass a type option, such as { type: 'application/*+json' }, so matching is delegated to the configured media-type test.
QHow does the limit option work?
The limit option controls the maximum request-body size. A numeric value is interpreted as bytes, while a string is interpreted by the bytes library.
Follow-up: Why configure a limit? A bounded body size reduces exposure to unexpectedly large payloads; choose a value appropriate for the endpoint rather than relying blindly on the default.
QHow are compressed request bodies handled?
The middleware automatically handles gzip and deflate encodings by inflating them before parsing. Set inflate to false when compressed bodies should be rejected.
Follow-up: What happens when the request has a nonmatching Content-Type? The JSON parser skips it, and the documentation says req.body becomes an empty object when the type is not matched.
Related
express.urlencoded()express.raw()express.text()app.use()req.bodybody-parser