Node.js Reference ยท Web APIs in Node.js
fetch versus http.request in Node.js
Compare fetch() and http.request() in Node.js: API style, streaming, error handling, redirects, timeouts and when each client is the better choice.
Node.js has two built-in HTTP clients. fetch() is the web-standard, promise-based client: the same function you know from browsers, with Request, Response and Headers objects. http.request() (and https.request()) is the older, callback and stream based client from the node:http module, with more knobs and more code.
For most new code fetch() is the better default. http.request() is still the right tool when you need things fetch() does not expose: raw sockets, custom agents with fine control, exact header casing, upgrade requests or HTTP/1.1 details. This page explains the differences, with runnable examples against a loopback server.
How they compare
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 main differences:
fetch() |
http.request() |
|
|---|---|---|
| Style | Promise, async/await |
Callback and events, you wire streams |
| Body helpers | json(), text(), arrayBuffer(), blob() |
None; collect chunks yourself |
| Request body | string, Buffer, FormData, URLSearchParams, stream |
write to the request stream |
| Redirects | Followed automatically (up to 20) | Not followed |
| Cancel | AbortSignal |
AbortSignal option or req.destroy() |
| Keep-alive | On by default | Off by default unless an Agent enables it |
| Portable | Same API in browsers and Deno | Node.js only |
Errors and failures
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.
Choosing a client
- Use
fetch()for ordinary API calls, JSON, form posts and code shared with browsers. It is short, redirects work, andAbortSignal.timeout()handles deadlines. - Use
http.request()for proxies and tunnels,UpgradeandCONNECTrequests, customAgentbehavior, access to the rawsocket, sending unusual or case-sensitive headers, or streaming a request body incrementally while also reading the response. - Use the
undicipackage (undici) when you need connection pools, a mock for tests or the fasterrequest()function; it complementsfetch()rather than replacing it. - Streaming works in both.
response.bodyfromfetch()is a webReadableStream; a response fromhttp.request()is a Node.jsReadable. Convert withReadable.fromWeb()andReadable.toWeb(). - Cookies are not managed by either. Neither client keeps a cookie jar; you read
Set-Cookieand sendCookieyourself or use a library. - Do not forget to read the body. With
fetch(), an unread body holds the connection; withhttp.request(), an unreadresstalls the socket until you callres.resume().
Related
fetch(),undici,AbortSignal- Lessons: HTTP client, Abort signals