doc: Add URL argument with http/https request

PR-URL: https://github.com/nodejs/node/pull/13405
Fixes: https://github.com/nodejs/node/issues/13383
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Timothy Gu <timothygu99@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Yuta Hiroto <hello@about-hiroppy.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

2 files changed, 55 insertions, 10 deletions

diff --git a/doc/api/http.md b/doc/api/http.md
index 2ceeaf6dac..b062736565 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -1568,9 +1568,13 @@ added to the [`'request'`][] event.
 ## http.get(options[, callback])
 <!-- YAML
 added: v0.3.6
+changes:
+  - version: v7.5.0
+    pr-url: https://github.com/nodejs/node/pull/10638
+    description: The `options` parameter can be a WHATWG `URL` object.
 -->
 
-* `options` {Object | string} Accepts the same `options` as
+* `options` {Object | string | URL} Accepts the same `options` as
   [`http.request()`][], with the `method` always set to `GET`.
   Properties that are inherited from the prototype are ignored.
 * `callback` {Function}
@@ -1636,9 +1640,13 @@ requests.
 ## http.request(options[, callback])
 <!-- YAML
 added: v0.3.6
+changes:
+  - version: v7.5.0
+    pr-url: https://github.com/nodejs/node/pull/10638
+    description: The `options` parameter can be a WHATWG `URL` object.
 -->
 
-* `options` {Object | string}
+* `options` {Object | string | URL}
   * `protocol` {string} Protocol to use. Defaults to `http:`.
   * `host` {string} A domain name or IP address of the server to issue the
     request to. Defaults to `localhost`.
@@ -1677,8 +1685,9 @@ added: v0.3.6
 Node.js maintains several connections per server to make HTTP requests.
 This function allows one to transparently issue requests.
 
-`options` can be an object or a string. If `options` is a string, it is
-automatically parsed with [`url.parse()`][].
+`options` can be an object, a string, or a [`URL`][] object. If `options` is a
+string, it is automatically parsed with [`url.parse()`][]. If it is a [`URL`][]
+object, it will be automatically converted to an ordinary `options` object.
 
 The optional `callback` parameter will be added as a one time listener for
 the [`'response'`][] event.
@@ -1750,6 +1759,18 @@ There are a few special headers that should be noted.
 * Sending an Authorization header will override using the `auth` option
   to compute basic authentication.
 
+Example using a [`URL`][] as `options`:
+
+```js
+const { URL } = require('url');
+
+const options = new URL('http://abc:xyz@example.com');
+
+const req = http.request(options, (res) => {
+  // ...
+});
+```
+
 [`'checkContinue'`]: #http_event_checkcontinue
 [`'listening'`]: net.html#net_event_listening
 [`'request'`]: #http_event_request
@@ -1757,6 +1778,7 @@ There are a few special headers that should be noted.
 [`Agent`]: #http_class_http_agent
 [`EventEmitter`]: events.html#events_class_eventemitter
 [`TypeError`]: errors.html#errors_class_typeerror
+[`URL`]: url.html#url_the_whatwg_url_api
 [`agent.createConnection()`]: #http_agent_createconnection_options_callback
 [`destroy()`]: #http_agent_destroy
 [`http.Agent`]: #http_class_http_agent
diff --git a/doc/api/https.md b/doc/api/https.md
index 0f42366a70..f4000335a0 100644
--- a/doc/api/https.md
+++ b/doc/api/https.md
@@ -115,15 +115,20 @@ See [`http.listen()`][] for details.
 ## https.get(options[, callback])
 <!-- YAML
 added: v0.3.6
+changes:
+  - version: v7.5.0
+    pr-url: https://github.com/nodejs/node/pull/10638
+    description: The `options` parameter can be a WHATWG `URL` object.
 -->
-- `options` {Object | string} Accepts the same `options` as
+- `options` {Object | string | URL} Accepts the same `options` as
   [`https.request()`][], with the `method` always set to `GET`.
 - `callback` {Function}
 
 Like [`http.get()`][] but for HTTPS.
 
-`options` can be an object or a string. If `options` is a string, it is
-automatically parsed with [`url.parse()`][].
+`options` can be an object, a string, or a [`URL`][] object. If `options` is a
+string, it is automatically parsed with [`url.parse()`][]. If it is a [`URL`][]
+object, it will be automatically converted to an ordinary `options` object.
 
 Example:
 
@@ -153,8 +158,12 @@ Global instance of [`https.Agent`][] for all HTTPS client requests.
 ## https.request(options[, callback])
 <!-- YAML
 added: v0.3.6
+changes:
+  - version: v7.5.0
+    pr-url: https://github.com/nodejs/node/pull/10638
+    description: The `options` parameter can be a WHATWG `URL` object.
 -->
-- `options` {Object | string} Accepts all `options` from [`http.request()`][],
+- `options` {Object | string | URL} Accepts all `options` from [`http.request()`][],
   with some differences in default values:
   - `protocol` Defaults to `https:`
   - `port` Defaults to `443`.
@@ -168,8 +177,9 @@ The following additional `options` from [`tls.connect()`][] are also accepted wh
   custom [`Agent`][]:
   `pfx`, `key`, `passphrase`, `cert`, `ca`, `ciphers`, `rejectUnauthorized`, `secureProtocol`, `servername`
 
-`options` can be an object or a string. If `options` is a string, it is
-automatically parsed with [`url.parse()`][].
+`options` can be an object, a string, or a [`URL`][] object. If `options` is a
+string, it is automatically parsed with [`url.parse()`][]. If it is a [`URL`][]
+object, it will be automatically converted to an ordinary `options` object.
 
 Example:
 
@@ -235,7 +245,20 @@ const req = https.request(options, (res) => {
 });
 ```
 
+Example using a [`URL`][] as `options`:
+
+```js
+const { URL } = require('url');
+
+const options = new URL('https://abc:xyz@example.com');
+
+const req = https.request(options, (res) => {
+  // ...
+});
+```
+
 [`Agent`]: #https_class_https_agent
+[`URL`]: url.html#url_the_whatwg_url_api
 [`http.Agent`]: http.html#http_class_http_agent
 [`http.Server#keepAliveTimeout`]: http.html#http_server_keepalivetimeout
 [`http.Server#setTimeout()`]: http.html#http_server_settimeout_msecs_callback