README
Heel
Efficient promise-based HTTP request library.
Features
- Lightweight (no dependencies)
- Easy to use
- Full Promises support
- Auto handle compressed responses (gzip, deflate)
- Auto parse response body (json)
- Auto detect and set content type
Install
npm install heel
You will need git
installed and added to PATH
for github installs
Examples
Basic Get (json)
const heel = require('heel');
heel('https://example.com/api')
.json()
.then((res) => console.log(res.body))
.catch((err) => console.error(err));
Headers
heel('https://example.com')
.set('Authorization', 'Key')
.set({
'key': 'value',
'another': 'foo'
})
.set('Authorization=foobar')
.set(heel.bearer('foobar'))
.then(console.log)
.catch(console.error)
Querystrings
heel('https://example.com')
.query({ limit: 5 })
.query('key=value')
.query('key', 'value')
.then((r) => console.log(r.body))
.catch((e) => console.error(e));
Post Requests
heel.post('https://post.com')
.send({ some: 'json' })
.set(heel.bearer(process.env.API_KEY))
.then(console.log)
.catch(console.error);
Similar way is possible with other methods heel.[get|post|put|patch|delete]
with get being default if no method specified
Async/Await
(async() => {
const res = await heel('https://example.com')
.set('key', 'value')
.query({ limit: 3 });
console.log(res.body);
})();
Instances
Instances are powerful way to do many requests with lot of options instead of duplicating code
const heel = require('heel');
const api = heel.create({
baseURL: 'https://baseurl.com',
headers: { key: 'value' },
method: 'post',
plugins: [plugin1, plugin2],
query: { limit: 5 }
});
api('/endpoint')
.send({ json: 'data' })
.then(console.log)
.catch(console.error);
Status Codes
By default the library rejects the promise on 4xx
and 5xx
Errors but it is possible to override that behavior and validate status yourself using req.status()
heel('https://example.com')
.status((s) => s < 500)
.then((res) => console.log(res.body));
As always all chainable methods are also available on instances to reduce duplications or even override the global instance
const heel = require('heel');
heel.status((s) => s < 500);
heel('https://example.com')
.then((res) => console.log(res.body));
const api = heel.create({ baseURL: 'https://example.com' })
.status((s) => s < 500);
api('/route')
.then((res) => console.log(res.body));