This package has been deprecated

Author message:

No longer maintained, please use node-fetch

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));