Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Web APIs in Node.js

Node.js Request class

Reference for the Request class in Node.js: create requests, read url, method, headers and body, clone them, and pass them to fetch().

A Request describes an HTTP request as an object: a URL, a method, headers, an optional body and a few behavior settings. You pass one to fetch() instead of a URL and an options object, which is useful when you want to build, validate or copy a request before sending it.

Request is a global class in Node.js and follows the standard shared with browsers. Because it validates its input, constructing one is also a cheap way to check that a URL, a method and a header set are legal. Unlike in a browser, a URL must be absolute because Node has no page location to resolve against.

NODE
const request = new Request('http://localhost/api', {
  method: 'POST',
  body: 'hello',
});
console.log(request.method, request.url); // POST http://localhost/api

Try it

Node.js Properties and normalization

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.

Node.js Cloning, copying and validation

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.

Syntax

NODE
new Request(input[, init])

input is a URL string, a URL object or another Request. init accepts the same options as fetch(): method, headers, body, signal, redirect, duplex, keepalive, credentials, cache, mode, referrer, referrerPolicy and integrity. Options in init override the ones copied from a Request given as input.

Property Description
url The full, normalized URL string (for example http://example.test/ when you pass http://example.test).
method Upper-case method.
headers A Headers object.
body A ReadableStream, or null when there is no body.
bodyUsed true after the body was read.
signal An AbortSignal that follows the one you passed.
redirect, credentials, cache, mode, destination, referrer, referrerPolicy, integrity, keepalive, duplex Behavior settings with their standard defaults ('follow', 'same-origin', 'default', 'cors' ...).
Method Description
text() Promise for the body as a string (UTF-8).
json() Promise for the parsed JSON body; rejects with SyntaxError when the text is not valid JSON.
arrayBuffer(), bytes(), blob() Promises for binary forms of the body.
formData() Promise for a FormData parsed from a multipart or urlencoded body.
clone() A second Request with its own copy of the body. Throws if the body was used.

Errors: TypeError for a relative URL, a URL with credentials (user:pass@), a forbidden or invalid method (CONNECT, TRACE, TRACK), a body with GET or HEAD, an illegal header, or a stream body without duplex: 'half'. Reading a body twice rejects with TypeError ("Body is unusable").

Usage notes

  • Only GET, POST, PUT, DELETE, HEAD and OPTIONS are upper-cased for you. Write PATCH in capitals, or the server may receive a lower-case method (undici also prints a warning for lower-case patch).
  • A string body sets content-type to text/plain;charset=UTF-8 when you have not set one. URLSearchParams gives the urlencoded type; FormData gives multipart with a boundary; Blob uses its own type; a Buffer sets none.
  • The body is a one-shot stream. Read it with exactly one of text(), json(), and so on, or call clone() first. Cloning big streamed bodies buffers data in memory.
  • fetch(request) consumes the body, so it cannot be sent twice. To retry, build a fresh Request or clone before sending.
  • Several settings are placeholders in Node. credentials, cache, mode and referrer are stored but do not change what undici sends.
  • Use new Request(input, init) for validation. It is the quickest way to find out whether a URL, method and header set will be accepted.
  • Servers can use it too. Frameworks that follow the web-standard handler style ((request) => Response) construct a Request from the incoming Node request.
  • bytes() was added in Node 22.