README.md

requisition

A light, fluent node.js HTTP client for ES6. Heavily inspired by superagent as well as fetch. Designed with ES7 async/await in mind.

The API is quite minimal for now. Features will be added while people request or use them.

const req = require('requisition');

// GET a JSON body
async function () {
  const res = await req('/users.json');
  const body = await res.json();
}

// POST an image file
async function () {
  const res = await req.post('/images.json').sendFile('image.png');
  const body = await res.json();
}

Differences

This is similar to other AJAX libraries like axios except:

• Does not have browser support
• Does not depend on gigantic options objects
• Many utilities for handling HTTP responses like saving to a file

API

const request = require('requisition');

Request

request(url)

GET a url, return the response object.

request[VERB](url)

VERB a url, specifically when it's not GET.

request().then( response => )

Send the request and wait for the response.

request('/').then(function (response) {

})

request().set(headers)

Set an object of headers.

request().set(header, value)

Set a single header.

request().auth(name, pass)

Add basic authorization.

request().agent(agent)

Set http agent.

request().timeout(ms)

Set timeout.

request().redirects(num)

Set max redirect times.

request().ifModifiedSince(date)

Set header If-Modified-Since.

request().ifNoneMatch(value)

Set header If-None-Match.

request().type(type)

Set header Content-Type.

request().cookie(key, value, options)

Set cookie, uses cookie.serialize()

request('/cookie')
  .cookie(name, value, options)
  .then(function (response) {
    console.info(response.cookies);
  })

request().query(params)

Add query string.

request().send(data)

Add http body.

request().sendFile(filename)

Send file.

Response

response.status

The status code of the response.

response.headers

The header object of the response.

response.is(types...)

Infer the Content-Type of the response, similar to Koa or Express' method. See type-is.

response.get(header)

Get the value for a header.

response.charset

Get charset.

response.etag

Get header ETag.

response.lastModified

Get header Last-Modified.

response.cookies

Get cookies

request('/cookie').then(function (response) {
  console.info(response.cookies);
})

response.buffer().then( buffer => )

Return a single Buffer for the entire response.

response.text().then( text => )

Return a single String for the entire response.

response.json().then( body => )

Automatically parse the JSON of the response.

request('/users.json').then(function (response) {
  assert(response.status === 200, 'Bad response!');
  assert(response.is('json'), 'Bad type!');
  return response.json()
}).then(function (body) {
  console.log(body);
})

response.saveTo([filename]).then( filename => )

Save the response to a file. If no filename is specified, saves to a random file in your temporary directory.

request('/file.txt').then(function (response) {
  return response.saveTo('/tmp/file.txt');
}).then(function () {
  console.log('file saved!');
})

response.dump()

Dumps the response. Execute this if you haven't handled the body.

response.destroy()

Destroy the response.