Features
Promise- based HTTP requestor- Works with HTTP and HTTPS protocols
- Automatically handles JSON requests and responses
- Extremely lightweight with no dependencies 678 bytes!
- Includes aliases for common HTTP verbs:
get,post,put,patch, anddel
Additionally, this module is delivered as:
- ES Module:
dist/httpie.mjs - CommonJS:
dist/httpie.js
Install
$ npm install --save httpie
Usage
Note: The
asyncsyntax is for demo purposes – you may use Promises in a Node 6.x environment too!
; try const data = await ; // Demo: Endpoint will echo what we've sent const res = await ; console; //=> 201 console; //=> { id: 1, name: 'bulbasaur', number: 1, moves: [{...}, {...}] } catch err console; console; console;API
send(method, url, opts={})
Returns: Promise
Any httpie.send request (and its aliases) will always return a Promise.
If the response's statusCode is 400 or above, this Promise will reject with a formatted error – see Error Handling. Otherwise, the Promise will resolve with the full ClientRequest stream.
The resolved response will receive a new data key, which will contain the response's full payload. Should the response return JSON content, then httpie will parse it and the res.data value will be the resulting JSON object!
method
Type: String
The HTTP method name – it must be uppercase!
url
Type: String or URL
If url is a string, it is automatically parsed with url.parse() into an object.
opts.body
Type: Mixed
Default: undefined
The request's body, can be of any type!
Any non-Buffer objects will be converted into a JSON string and the appropriate Content-Type header will be attached.
Additionally, httpie will always set a value for the Content-Length header!
opts.headers
Type: Object
Default: {}
The custom headers to send with your request.
opts.redirect
Type: Boolean
Default: true
Whether or not redirect responses should be followed automatically.
Note: This may only happen with a 3xx status and if the response had a
Locationheader.
opts.reviver
Type: Function
Default: undefined
An optional function that's passed directly to JSON.parse, allowing you transform aspects of the response data before the httpie request resolves.
Note: This will only run if
httpiedetects that JSON is contained in the response!
get(url, opts={})
Alias for
send('GET', url, opts).
post(url, opts={})
Alias for
send('POST', url, opts).
put(url, opts={})
Alias for
send('PUT', url, opts).
patch(url, opts={})
Alias for
send('PATCH', url, opts).
del(url, opts={})
Alias for
send('DELETE', url, opts).
Error Handling
All responses with statusCode >= 400 will result in a rejected httpie request. When this occurs, an Error instance is formatted with complete information:
err.message–String– Identical toerr.statusMessage;err.statusMessage–String– The response'sstatusMessagevalue;err.statusCode–Number– The response'sstatusCodevalue;err.headers–Object– The response'sheadersobject;err.data–Mixed– The response's payload;
Important: The error's
dataproperty may also be parsed to a JSON object, according to the response's headers.
; ;//=> "(404) Not Found"//=> "text/html; charset=UTF-8"//=> ~> <?xml version="1.0" encoding="iso-8859-1"?>\n<!DOCTYPE html ...</body>\n</html>License
MIT © Luke Edwards