Skip to content

doc: clarify http.request supports headers as array #58769

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Dinesh0007000 wants to merge 3 commits into
base: main
Choose a base branch
from
+14 −1
Open

doc: clarify http.request supports headers as array #58769

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
587e116
doc: clarify http.request supports headers as array
Dinesh0007000 Jun 20, 2025
c6d7760
doc: clarify headers array format in http.request options
Dinesh0007000 Jun 20, 2025
7df7f2d
fix: address markdown linting issues and link formatting
Dinesh0007000 Jun 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion doc/api/http.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3820,7 +3820,9 @@ changes:
* `family` {number} IP address family to use when resolving `host` or
`hostname`. Valid values are `4` or `6`. When unspecified, both IP v4 and
v6 will be used.
* `headers` {Object} An object containing request headers.
* `headers` {Object | Array} Request headers to send with the request. This can be:
* An object like `{ 'Content-Type': 'application/json' }`, or
* An array of key-value pairs like `[ 'Content-Type', 'text/plain', 'X-Custom', 'yes' ]`, similar to how headers are passed to `response.writeHead()`.
Copy link
Copy Markdown
Member

@pimterry pimterry Jun 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a series of extra spaces here (are passed), and this line is very long, which will be why the markdown linting is failing here. Can you fix that? You can run the markdown linting locally by running make lint-md.

"An array of key-value pairs" is not clear I think - that will make people think of [["key1", "value1"], ["key2", "value2"]] which is not what's happening. We should be specific that this is a flat array of values, not tuples, since this can be confusing.

I think it would be good to link to response.writeHead here, and request.rawHeaders as well (which uses the same format).

It might be better to keep the text inline here simple (a very short explanation of "headers object or flat array of raw headers" or similar) and then include the larger explanation & examples as a paragraph in the text below. What do you think? See what looks best - you can test the docs locally by running make docserve and then looking at http://localhost:8000.

* `hints` {number} Optional [`dns.lookup()` hints][].
* `host` {string} A domain name or IP address of the server to issue the
request to. **Default:** `'localhost'`.
Expand Down
Loading