AJ ONeal a95d003ed5 | ||
---|---|---|
examples | ||
tests | ||
.gitignore | ||
.prettierrc | ||
EXTRA.md | ||
LICENSE | ||
README.md | ||
index.js | ||
package-lock.json | ||
package.json |
README.md
µRequest | a Root project
Minimalist HTTP client
A lightweight alternative to (and 80/20 drop-in replacement for) request.
Has the 20% of features that 80%+ of people need, in about 500 LoC.
Written from scratch, with zero-dependencies.
Super simple to use
µRequest is designed to be a drop-in replacement for request. It supports HTTPS and follows redirects by default.
npm install --save @root/request
# or npm install git+ssh://git@git.therootcompany.com/request.js
var request = require('@root/request');
request('http://www.google.com', function (error, response, body) {
console.log('error:', error); // Print the error if one occurred
console.log('statusCode:', response && response.statusCode); // Print the response status code if a response was received
console.log('body:', body); // Print the HTML for the Google homepage.
});
Using Promises
var request = require('@root/request');
request('http://www.google.com')
.then(function (response) {
console.log('statusCode:', response.statusCode); // Print the response status code if a response was received
console.log('body:', response.body); // Print the HTML for the Google homepage.
})
.catch(function (error) {
console.log('error:', error); // Print the error if one occurred
});
Streaming
In order to keep this library lightweight, performant, and keep the code easy to
read, the streaming behavior is slightly different from that of
request.js
.
-var request = require('request');
+var request = require('@root/request');
-var stream = request({ url, headers });
+var stream = await request({ url, headers });
let attachment = await new MailgunAPI.Attachment({
data: stream
})
Example:
var request = require('@root/request');
var resp = await request({
url: 'http://www.google.com',
stream: true // true | 'filename.ext' | stream.Writable
});
// 'resp' itself is a ReadableStream
resp.on('data', function () {
// got some data
});
resp.on('end', function () {
// the data has ended
});
// 'resp.stream' is a Promise that is resolved when the read stream is destroyed
await resp.stream; // returns `undefined`
console.log('Done');
The difference is that we don't add an extra layer of stream abstraction. You must use the response from await, a Promise, or the callback.
You can also give a file path:
request({
url: 'http://www.google.com',
stream: '/tmp/google-index.html'
});
Which is equivalent to passing a write stream for the file:
request({
url: 'http://www.google.com',
stream: fs.createWriteStream('/tmp/google-index.html')
});
Table of contents
Forms
urequest
supports application/x-www-form-urlencoded
and multipart/form-data
form uploads.
application/x-www-form-urlencoded (URL-Encoded Forms)
URL-encoded forms are simple.
request.post('http://service.com/upload', { form: { key: 'value' } });
// or
request.post(
{ url: 'http://service.com/upload', form: { key: 'value' } },
function (err, httpResponse, body) {
/* ... */
}
);
multipart/form-data (Multipart Form Uploads)
For multipart/form-data
we use the form-data library by @felixge. For the most cases, you can pass your upload form data via the formData
option.
To use form-data
, you must install it separately:
npm install --save form-data@2.x
var formData = {
// Pass a simple key-value pair
my_field: 'my_value',
// Pass data via Buffers
my_buffer: Buffer.from([1, 2, 3]),
// Pass data via Streams
my_file: fs.createReadStream(__dirname + '/unicycle.jpg'),
// Pass multiple values /w an Array
attachments: [
fs.createReadStream(__dirname + '/attachment1.jpg'),
fs.createReadStream(__dirname + '/attachment2.jpg')
],
// Pass optional meta-data with an 'options' object with style: {value: DATA, options: OPTIONS}
// Use case: for some types of streams, you'll need to provide "file"-related information manually.
// See the `form-data` README for more information about options: https://github.com/form-data/form-data
custom_file: {
value: fs.createReadStream('/dev/urandom'),
options: {
filename: 'topsecret.jpg',
contentType: 'image/jpeg'
}
}
};
request.post(
{ url: 'http://service.com/upload', formData: formData },
function optionalCallback(err, httpResponse, body) {
if (err) {
return console.error('upload failed:', err);
}
console.log('Upload successful! Server responded with:', body);
}
);
See the form-data README for more information & examples.
HTTP Authentication
request.get('http://some.server.com/', {
auth: {
user: 'username',
pass: 'password',
sendImmediately: false
}
});
// or
request.get('http://some.server.com/', {
auth: {
bearer: 'bearerToken'
}
});
If passed as an option, auth
should be a hash containing values:
user
||username
pass
||password
bearer
(optional)
Note that you can also specify basic authentication using the URL itself, as
detailed in RFC 1738. Simply pass the
user:password
before the host with an @
sign:
var username = 'username',
password = 'password',
url = 'http://' + username + ':' + password + '@some.server.com';
request({ url: url }, function (error, response, body) {
// Do more stuff with 'body' here
});
Bearer authentication is supported, and is activated when the bearer
value is
available. The value may be either a String
or a Function
returning a
String
. Using a function to supply the bearer token is particularly useful if
used in conjunction with defaults
to allow a single function to supply the
last known token at the time of sending a request, or to compute one on the fly.
Custom HTTP Headers
HTTP Headers, such as User-Agent
, can be set in the options
object.
In the example below, we call the github API to find out the number
of stars and forks for the request repository. This requires a
custom User-Agent
header as well as https.
var request = require('request');
var options = {
url: 'https://api.github.com/repos/request/request',
headers: {
'User-Agent': 'request'
}
};
function callback(error, response, body) {
if (!error && response.statusCode == 200) {
var info = JSON.parse(body);
console.log(info.stargazers_count + ' Stars');
console.log(info.forks_count + ' Forks');
}
}
request(options, callback);
UNIX Domain Sockets
urequest
supports making requests to UNIX Domain Sockets. To make one, use the following URL scheme:
/* Pattern */ 'http://unix:SOCKET:PATH';
/* Example */ request.get(
'http://unix:/absolute/path/to/unix.socket:/request/path'
);
Note: The SOCKET
path is assumed to be absolute to the root of the host file system.
request(options, callback)
The first argument can be either a url
or an options
object. The only required option is uri
; all others are optional.
uri
||url
- fully qualified uri or a parsed url object fromurl.parse()
method
- http method (default:"GET"
)headers
- http headers (default:{}
)
body
- entity body for PATCH, POST and PUT requests. Must be aBuffer
,String
orReadStream
. Ifjson
istrue
, thenbody
must be a JSON-serializable object.json
- setsbody
to JSON representation of value and addsContent-type: application/json
header. Additionally, parses the response body as JSON.
followRedirect
- follow HTTP 3xx responses as redirects (default:true
). This property can also be implemented as function which getsresponse
object as a single argument and should returntrue
if redirects should continue orfalse
otherwise.followAllRedirects
- follow non-GET HTTP 3xx responses as redirects (default:false
)followOriginalHttpMethod
- by default we redirect to HTTP method GET. you can enable this property to redirect to the original HTTP method (default:false
)maxRedirects
- the maximum number of redirects to follow (default:10
)removeRefererHeader
- removes the referer header when a redirect happens (default:false
). Note: if true, referer header set in the initial request is preserved during redirect chain.
encoding
- encoding to be used onsetEncoding
of response data. Ifnull
, thebody
is returned as aBuffer
. Anything else (including the default value ofundefined
) will be passed as the encoding parameter totoString()
(meaning this is effectivelyutf8
by default). (Note: if you expect binary data, you should setencoding: null
.)
Convenience methods
There are also shorthand methods for different HTTP METHODs and some other conveniences.
request.defaults(options)
This method returns a wrapper around the normal request API that defaults to whatever options you pass to it.
Note: request.defaults()
does not modify the global request API;
instead, it returns a wrapper that has your default settings applied to it.
Note: You can call .defaults()
on the wrapper that is returned from
request.defaults
to add/override defaults that were previously defaulted.
For example:
//requests using baseRequest() will set the 'x-token' header
var baseRequest = request.defaults({
headers: { 'x-token': 'my-token' }
});
//requests using specialRequest() will include the 'x-token' header set in
//baseRequest and will also include the 'special' header
var specialRequest = baseRequest.defaults({
headers: { special: 'special value' }
});
request.METHOD()
These HTTP method convenience functions act just like request()
but with a default method already set for you:
- request.get(): Defaults to
method: "GET"
. - request.post(): Defaults to
method: "POST"
. - request.put(): Defaults to
method: "PUT"
. - request.patch(): Defaults to
method: "PATCH"
. - request.del() / request.delete(): Defaults to
method: "DELETE"
. - request.head(): Defaults to
method: "HEAD"
. - request.options(): Defaults to
method: "OPTIONS"
.
Debugging
There are at least two ways to debug the operation of request
:
-
Launch the node process like
NODE_DEBUG=urequest node script.js
(lib,request,otherlib
works too). -
Set
require('@root/request').debug = true
at any time (this does the same thing as #1).