Skip to content
Tutorials Center
My learning

Topics

Lesson 52 of 133 ยท Networking and HTTP

Request Bodies, JSON and Forms

Learn how Node.js servers read request bodies - collecting stream chunks, size limits, JSON parse errors, URL-encoded forms, a hand-written multipart parser and content negotiation.

A GET request is just a question: the URL and headers say everything. A POST, PUT or PATCH carries a body, the data the client wants you to store or process. In Node.js the body does not arrive as a ready-made object. It arrives as a stream of byte chunks, and it is your job to collect it, check that it is not absurdly large, decode it and parse it.

This lesson builds that skill from the ground up: reading the body stream, enforcing a size limit, parsing JSON and reporting bad input properly, handling HTML form data, parsing a multipart upload by hand, and choosing a response format with content negotiation. Frameworks hide all of this behind express.json() or await request.json(), but you will write better servers once you know what those helpers do. If you have not yet seen how req and res work, read The http Module: Servers first.

The body is a stream

The req object is a readable stream (see Readable Streams). Its chunks are Buffer objects, not strings. A chunk can end in the middle of a multi-byte character such as รฉ, so you must not convert each chunk to a string separately. The safe recipe is: collect the buffers, join them with Buffer.concat(), and decode once at the end.

Node.js Collecting a request body

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that bytes is larger than characters: รฉ takes two bytes in UTF-8 and the coffee cup three. This is why you never trust string.length to measure a body (Text, Encodings and Unicode explains why). A GET has an empty body, and for await simply finishes at once.

The for await loop reads the stream until the client finishes sending. A slow or malicious client can keep the connection open and send one byte a minute. Node's server has requestTimeout and headersTimeout settings that close such connections, and a production server should also put a deadline on body reading.

Always set a size limit

If you collect whatever arrives, a client can send a 10 GB body and your process runs out of memory. Every body reader needs a maximum size. There are two checks:

  1. The Content-Length header announces the size up front. If it is already too big, answer 413 Content Too Large immediately, without reading anything.
  2. A chunked upload has no length header, so count the bytes while reading and stop collecting when the total passes the limit.

When the limit is crossed, do not simply destroy the request: that kills the socket and the client never sees your 413. Keep draining the stream (without storing it) and answer afterwards. This version shows both checks, plus a small error class so the handler can turn failures into status codes.

Node.js A body reader with a size limit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The third request is sent with Transfer-Encoding: chunked because the body is an async generator and fetch cannot know its length in advance (duplex: 'half' is required for stream bodies). Only the counting loop can catch it.

Real servers pick the limit per route: a few kilobytes for JSON APIs, tens of megabytes for uploads. Express's express.json() defaults to 100 KB for the same reason.

Parsing JSON

JSON is the usual body format for APIs. Parsing has three failure modes you should handle separately:

  • the Content-Type is not JSON (answer 415 Unsupported Media Type),
  • the text is not valid JSON (answer 400 Bad Request),
  • the JSON is valid but has the wrong shape (answer 422 Unprocessable Content, or 400).

A JSON.parse failure throws a SyntaxError. Let us see exactly what it says; it is a good idea to know the message you will log.

Node.js What a JSON syntax error looks like

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The messages are generated by V8 and have changed between Node versions, so do not match on the text. Match on error instanceof SyntaxError, and give the client your own stable message. Now put all three checks into a small server.

Node.js A JSON endpoint with proper error codes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The function returns { value } or { error } instead of throwing, which keeps the handler a flat list of early returns. You could equally throw an HttpError and catch it in one place; Middleware Pattern shows that style. Validation of the parsed value is a topic of its own: see Validating Input.

Be careful with what you do with parsed JSON. A body such as {"__proto__": {"admin": true}} is harmless to JSON.parse itself, but copying it into another object with a naive deep-merge function can pollute prototypes. Validate the shape and copy only the fields you expect. More in Web Application Security.

HTML forms: application/x-www-form-urlencoded

A plain HTML <form method="post"> sends application/x-www-form-urlencoded: the fields as name=Ada&city=Z%C3%BCrich, with spaces written as + and other special characters percent-encoded. You already know the class that parses this, URLSearchParams (see URLs, URLSearchParams and URLPattern). Pass it the body text.

Node.js Parsing a form body

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Checkboxes and multi-selects send the same name several times, so getAll() returns an array; get() would silently return only the first value. Everything in a form is a string: age=30 arrives as '30', and you convert and validate it yourself. An absent checkbox is simply missing, not false.

Also remember that a browser form can only send GET and POST. APIs consumed by JavaScript use fetch with JSON instead, and HTML forms that must "PUT" or "DELETE" use a hidden _method field that your server interprets.

Multipart form data (file uploads)

When a form has a file input (enctype="multipart/form-data"), the body is a sequence of parts separated by a boundary string. The Content-Type header names the boundary:

TEXT
Content-Type: multipart/form-data; boundary=----X1

Each part has its own headers, a blank line, and its content. The body looks like this (line breaks are \r\n):

TEXT
------X1
Content-Disposition: form-data; name="title"

Sunset
------X1
Content-Disposition: form-data; name="photo"; filename="a.txt"
Content-Type: text/plain

file contents here
------X1--

In production you would use a streaming parser (busboy, or the formData() method of a web Request). Writing a small buffer-based one teaches you the format and the pitfalls. Because the content can be binary, we split a Buffer, not a string. Here the client builds the body with FormData, and the server finds the boundary in the header and splits the parts.

Node.js A hand-written multipart parser

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The binary file survived because we never converted it to a string. Real parsers must additionally stream large files to disk instead of holding them in memory, limit the number and size of parts, and sanitise filename, which is attacker-controlled (see Paths, Permissions and Safe File Handling). Never use the client's filename as a path.

Node 24 can also do the work for you with web standards: await new Response(body, { headers }).formData() parses multipart and urlencoded bodies into a FormData. It is convenient for small bodies; it buffers the whole thing in memory.

Content negotiation

A client says which representations it understands with the Accept header, for example Accept: application/json, text/html;q=0.5. A q value (default 1) ranks the choices. The server picks the best match it can produce and says what it chose in Content-Type. If it can offer nothing acceptable, the correct reply is 406 Not Acceptable.

Node.js Choosing a format from the Accept header

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Vary: Accept tells caches that the response depends on that request header, otherwise a cache might hand the HTML version to a client that asked for JSON (Headers, Cookies and Caching covers this). Many APIs skip negotiation and only speak JSON, which is fine, but the same idea applies to Accept-Language and Accept-Encoding.

Pitfalls professionals avoid

  • Reading the body twice. A stream can be consumed only once. If a logging layer reads the body, the handler gets nothing. Read once, store the result (for example req.body), and share it.
  • Not reading the body at all. If you answer before reading a request body, leftover data stays on a keep-alive connection. Call req.resume() to discard it.
  • Trusting Content-Length. It is a claim by the client. Count the bytes you actually receive.
  • Converting chunks to strings one by one. This corrupts multi-byte characters at chunk edges.
  • Using GET with a body or POST for reads. Keep the semantics clean, as described in Designing REST APIs.
  • Forgetting that parse errors are the client's fault. A bad body is a 400, not a 500. A 500 pages someone at night for nothing.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why should you collect Buffer chunks and decode once instead of calling chunk.toString() on each chunk?

    A UTF-8 character such as รฉ uses two bytes, and a chunk boundary can fall between them. Joining the buffers first and decoding once avoids broken characters.
  2. 2. A client sends a 200 MB body to your JSON endpoint. What is the best protection?

    Without a limit the whole body is held in memory. A limit checked against Content-Length and the counted bytes protects the process, and 413 tells the client why.
  3. 3. Which status code fits a request whose body is not valid JSON?

    The client sent bad input, so it is a 4xx error. 400 is the standard code for a malformed body; 500 would wrongly signal a server bug.
  4. 4. A form posts lang=js&lang=sql. Which URLSearchParams call returns both values?

    get() returns only the first value for a name. getAll() returns an array with every value for that name.
  5. 5. Why does the multipart parser work on a Buffer rather than a string?

    A file part may contain arbitrary bytes. Decoding them as UTF-8 would replace invalid sequences, so the parser must split the raw bytes.

Summary

  • The request body is a readable stream of Buffer chunks; collect them, Buffer.concat(), then decode once.
  • Always enforce a maximum size: check Content-Length early and count bytes while reading; answer 413.
  • Separate the failures: 415 wrong content type, 400 invalid JSON, 422 valid JSON with the wrong shape.
  • Match errors with instanceof SyntaxError, not on V8's message text.
  • Urlencoded forms parse with URLSearchParams; use getAll() for repeated names and expect strings only.
  • Multipart bodies are boundary-separated parts; parse as bytes, stream big files, and never trust the filename.
  • Content negotiation reads Accept, answers 406 when nothing matches and sets Vary.

Next: Headers, Cookies and Caching