@trex-arms/httpie
v2.0.0-next.16
Published
A fork of lukeed/httpie
Downloads
7
Readme
Differences from httpie
- Added
err.request_uri
anderr.request_body
- Handles leading byte order marks in JSON responses
Features
Promise
- based HTTP requestor- Works with HTTP and HTTPS protocols
- Automatically handles JSON requests and responses
- Extremely lightweight with no dependencies! Less than 1000 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 @trex-arms/httpie
Usage
Note: The
async
syntax is for demo purposes – you may use Promises in a Node 6.x environment too!
import { get, post } from 'httpie';
try {
const { data } = await get('https://pokeapi.co/api/v2/pokemon/1');
// Demo: Endpoint will echo what we've sent
const res = await post('https://jsonplaceholder.typicode.com/posts', {
body: {
id: data.id,
name: data.name,
number: data.order,
moves: data.moves.slice(0, 6)
}
});
console.log(res.statusCode); //=> 201
console.log(res.data); //=> { id: 1, name: 'bulbasaur', number: 1, moves: [{...}, {...}] }
} catch (err) {
console.error('Error!', err.statusCode, err.message);
console.error('~> headers:', err.headers);
console.error('~> data:', err.data);
}
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
Location
header.
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
httpie
detects that JSON is contained in the response!
opts.timeout
Type: Integer
Default: undefined
The time, in milliseconds, before automatically terminating the request.
When the request exceeds this limit, httpie
rejects with an err<Error>
, adding a truthy err.timeout
value.
Important: There is a slight behavioral difference between the Node & browser versions! In the server, the
timeout
value does not propagate to any redirects. In the browser, thetimeout
value will not reset during redirects.
opts.withCredentials
Type: Boolean
Default: false
Whether or not cross-site requests should include credentials (such as cookies).
This value is passed directly to XMLHttpRequest.withCredentials
.
Important: This is for the browser version only!
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'sstatusMessage
value;err.statusCode
–Number
– The response'sstatusCode
value;err.headers
–Object
– The response'sheaders
object;err.data
–Mixed
– The response's payload;err.request_uri
–String
orURL
– The request's URI;err.request_body
–String
– The request's payload;
Additionally, errors that are a result of a timeout expiration will have a truthy err.timeout
value.
Important: The error's
data
property may also be parsed to a JSON object, according to the response's headers.
import { get } from 'httpie';
get('https://example.com/404').catch(err => {
console.error(`(${err.statusCode}) ${err.message}`)
console.error(err.headers['content-type']);
console.error(err.uri);
console.error(`~> ${err.data}`);
});
//=> "(404) Not Found"
//=> "text/html; charset=UTF-8"
//=> "https://example.com/404"
//=> ~> <?xml version="1.0" encoding="iso-8859-1"?>\n<!DOCTYPE html ...</body>\n</html>
License
MIT © Luke Edwards