grunt-http

Sends a HTTP request and deals with the response.

npm install grunt-http
60 downloads in the last day
382 downloads in the last week
3 481 downloads in the last month

grunt-http

Sends a HTTP request and deals with the response.

NPM

Getting Started

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-http --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-http');

The "http" task

Overview

In your project's Gruntfile, add a section named http to the data object passed into grunt.initConfig().

grunt.initConfig({
  http: {
    your_service: {
      options: {
        url: 'your/url.com',
      },
      dest: 'optional/file/to/save/response'
    }
  }
})

If you add a source file, the contents will be added to the body option unless another field is specified in the sourceField option.

Options

grunt-http uses the request module under the hood, and apart from a couple specific to grunt-http options, the rest get passed straight to it. Here's a copy of the of the module's option docs. Otherwise, go to the repo and have a look at what's it's capable of.

  • uri || url - fully qualified uri or a parsed url object from url.parse(). REQUIRED.
  • callback - A function that will receive an error, response and body, after a response if finished
  • qs - object containing querystring values to be appended to the uri
  • method - http method, defaults to GET
  • headers - http headers, defaults to {}
  • body - entity body for PATCH, POST and PUT requests. Must be buffer or string.
  • sourceField - A field in the body or form to add the source files' contents to. Can contain full stops to separate object path. Ie "form.js_code".
  • form - When passed an object, this sets body to a querystring representation of value, and adds Content-type: application/x-www-form-urlencoded; charset=utf-8 header. When passed no options, a FormData instance is returned (and is piped to request). For multipart/form-data install the optional dependency npm i form-data.
  • auth - A hash containing values user || username, password || pass, and sendImmediately (optional). See more info here.
  • json - sets body but to JSON representation of value and adds Content-type: application/json header. Additionally, parses the response body as json.
  • multipart - (experimental) array of objects which contains their own headers and body attribute. Sends multipart/related request. See example below.
  • followRedirect - follow HTTP 3xx responses as redirects. defaults to true.
  • followAllRedirects - follow non-GET HTTP 3xx responses as redirects. defaults to false.
  • maxRedirects - the maximum number of redirects to follow, defaults to 10.
  • encoding - Encoding to be used on setEncoding of response data. If set to null, the body is returned as a Buffer.
  • pool - A hash object containing the agents for these requests. If omitted this request will use the global pool which is set to node's default maxSockets.
  • pool.maxSockets - Integer containing the maximum amount of sockets in the pool.
  • timeout - Integer containing the number of milliseconds to wait for a request to respond before aborting the request
  • proxy - An HTTP proxy to be used. Support proxy Auth with Basic Auth the same way it's supported with the url parameter by embedding the auth info in the uri.
  • oauth - Options for OAuth HMAC-SHA1 signing. See more info here. The oauth-sign module must be installed to use this functionality.
  • hawk - Options for Hawk signing. The credentials key must contain the necessary signing info, see hawk docs for details. You will need to install the hawk module to use this functionality.
  • strictSSL - Set to true to require that SSL certificates be valid. Note: to use your own certificate authority, you need to specify an agent that was created with that ca as an option.
  • jar - If true, remember cookies for future use (or define your custom cookie jar; see mikeal/request's examples). To get either of these functions working you'll need to install an optional dependecy npm i tough-cookie.
  • aws - object containing aws signing information, should have the properties key and secret as well as bucket unless you're specifying your bucket as part of the path, or you are making a request that doesn't use a bucket (i.e. GET Services). You will need to install the aws-sign2 module to use this functionality.
  • httpSignature - Options for the HTTP Signature Scheme using Joyent's library. The http-signature module must be installed and the keyId and key properties must be specified.
  • localAddress - Local interface to bind for network connections.
  • ignoreErrors - Ignore the status code returned (if any).

There are a few optional dependencies you'll need to install to get certain functionality from this module.

  • if you wish to use cookies (jar) install tough-cookie
  • if you want to pass multipart/form-data you'll need to install form-data
  • if you wish to tunnel your requests install tunnel-agent
  • if you want to use Joyent's HTTP Signature Scheme, install http-signature
  • if you require oauth signing, you need to install the oauth-sign module
  • to use Hawk signing, you must use the hawk module
  • if you want to use AWS signing, you must install the aws-sign2 module

Google Closure

In this example, we're using google's closure service to compile a JS file.

grunt.initConfig({
  http: {
    closure: {
      options: {
        url: 'http://closure-compiler.appspot.com/compile',
        method: 'POST',
        form: {
          output_info: 'compiled_code',
          output_format: 'text',
          compilation_level: 'SIMPLE_OPTIMIZATIONS',
          warning_level: 'default'
        },
        sourceField: 'form.js_code'
      },
      files: {
        'build/main.js': 'src/main.js'
      }
    }
  }
});

multipart/form-data

In this example we're going to access the form data object directly to add an image to the POST fields.

Note, you need to install the form-data package before you can use this method.

var path = require('path');

grunt.initConfig({
  http: {
    multipart: {
      options: {
        url: 'http://posttestserver.com/post.php?dir=grunt-http',
        method: 'POST',
        form: function (form) {
          form.append('file', grunt.file.read(path.join(__dirname, 'images', 'pic.png')));
        }
      }
    }
  }
});

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

npm loves you