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.
const request = new Request('http://localhost/api', { method: 'POST', body: 'hello', }); console.log(request.method, request.url); // POST http://localhost/api
Try it
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.
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
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,HEADandOPTIONSare upper-cased for you. WritePATCHin capitals, or the server may receive a lower-case method (undici also prints a warning for lower-casepatch). - A string body sets
content-typetotext/plain;charset=UTF-8when you have not set one.URLSearchParamsgives the urlencoded type;FormDatagives multipart with a boundary;Blobuses its own type; aBuffersets none. - The body is a one-shot stream. Read it with exactly one of
text(),json(), and so on, or callclone()first. Cloning big streamed bodies buffers data in memory. fetch(request)consumes the body, so it cannot be sent twice. To retry, build a freshRequestor clone before sending.- Several settings are placeholders in Node.
credentials,cache,modeandreferrerare 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 aRequestfrom the incoming Node request. bytes()was added in Node 22.
Related
fetch(),Response,Headers,FormData,AbortSignal- Lessons: The HTTP client, Request bodies