From 60d14c870274e9f193a81e8eb9b6a74fba3b4178 Mon Sep 17 00:00:00 2001 From: Vladimir Trifonov Date: Fri, 2 Jun 2017 18:07:06 +0300 Subject: [PATCH] doc: Add URL argument with http/https request MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR-URL: https://github.com/nodejs/node/pull/13405 Fixes: https://github.com/nodejs/node/issues/13383 Reviewed-By: James M Snell Reviewed-By: Luigi Pinca Reviewed-By: Timothy Gu Reviewed-By: Colin Ihrig Reviewed-By: Tobias Nießen Reviewed-By: Yuta Hiroto Reviewed-By: Vse Mozhet Byt --- doc/api/http.md | 30 ++++++++++++++++++++++++++---- doc/api/https.md | 35 +++++++++++++++++++++++++++++------ 2 files changed, 55 insertions(+), 10 deletions(-) diff --git a/doc/api/http.md b/doc/api/http.md index 2ceeaf6dac04ea..b0627365659163 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -1568,9 +1568,13 @@ added to the [`'request'`][] event. ## http.get(options[, callback]) -* `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]) -* `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 0f42366a705255..f4000335a00770 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -115,15 +115,20 @@ See [`http.listen()`][] for details. ## https.get(options[, callback]) -- `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]) -- `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