HTTP

HTTP provides an HTTP request API on the client and server. To use these functions, add the HTTP package to your project by running in your terminal:

meteor add http

Anywhere

HTTP.call(method, url, [options], [asyncCallback])

import { HTTP } from 'meteor/http' (http/httpcall_client.js, line 19)

Perform an outbound HTTP request.

Arguments

method String

The HTTP method to use, such as "GET", "POST", or "HEAD".

url String

The URL to retrieve.

asyncCallback Function

Optional callback. If passed, the method runs asynchronously, instead of synchronously, and calls asyncCallback. On the client, this callback is required.

Options

content String

String to use as the HTTP request body.

data Object

JSON-able object to stringify and use as the HTTP request body. Overwrites content.

query String

Query string to go in the URL. Overwrites any query string in url.

params Object

Dictionary of request parameters to be encoded and placed in the URL (for GETs) or request body (for POSTs). If content or data is specified, params will always be placed in the URL.

auth String

HTTP basic authentication string of the form "username:password"

headers Object

Dictionary of strings, headers to add to the HTTP request.

timeout Number

Maximum time in milliseconds to wait for the request before failing. There is no timeout by default.

followRedirects Boolean

If true, transparently follow HTTP redirects. Cannot be set to false on the client. Default true.

npmRequestOptions Object

On the server, HTTP.call is implemented by using the npm request module. Any options in this object will be passed directly to the request invocation.

beforeSend Function

On the client, this will be called before the request is sent to allow for more direct manipulation of the underlying XMLHttpRequest object, which will be passed as the first argument. If the callback returns false, the request will be not be send.

This function initiates an HTTP request to a remote server.

On the server, this function can be run either synchronously or asynchronously. If the callback is omitted, it runs synchronously and the results are returned once the request completes successfully. If the request was not successful, an error is thrown. This is useful when making server-to-server HTTP API calls from within Meteor methods, as the method can succeed or fail based on the results of the synchronous HTTP call. In this case, consider using this.unblock() to allow other methods on the same connection to run in the mean time. On the client, this function must be used asynchronously by passing a callback.

Both HTTP and HTTPS protocols are supported. The url argument must be an absolute URL including protocol and host name on the server, but may be relative to the current host on the client. The query option replaces the query string of url. Parameters specified in params that are put in the URL are appended to any query string. For example, with a url of "/path?query" and params of {foo:"bar"}, the final URL will be "/path?query&foo=bar".

The params are put in the URL or the request body, depending on the type of request. In the case of request with no bodies, like GET and HEAD, the parameters will always go in the URL. For a POST or other type of request, the parameters will be encoded into the body with a standard x-www-form-urlencoded content type, unless the content or data option is used to specify a body, in which case the parameters will be appended to the URL instead.

When run in asynchronous mode, the callback receives two arguments, error and result. The error argument will contain an Error if the request fails in any way, including a network error, time-out, or an HTTP status code in the 400 or 500 range. In case of a 4xx/5xx HTTP status code, the response property on error matches the contents of the result object. When run in synchronous mode, either result is returned from the function, or error is thrown.

Contents of the result object:

statusCode Number

Numeric HTTP result status code, or null on error.

content String

The body of the HTTP response as a string.

data Object or null

If the response headers indicate JSON content, this contains the body of the document parsed as a JSON object.

headers Object

A dictionary of HTTP headers from the response.

Example server method:

Meteor.methods({checkTwitter: function (userId) {
  check(userId, String);
  this.unblock();
  try {
    var result = HTTP.call("GET", "http://api.twitter.com/xyz",
                           {params: {user: userId}});
    return true;
  } catch (e) {
    // Got a network error, time-out or HTTP error in the 400 or 500 range.

    return false;
  }
}});

Example asynchronous HTTP call:

HTTP.call("POST", "http://api.twitter.com/xyz",
          {data: {some: "json", stuff: 1}},
          function (error, result) {
            if (!error) {
              Session.set("twizzled", true);
            }
          });

Anywhere

HTTP.get(url, [callOptions], [asyncCallback])

import { HTTP } from 'meteor/http' (http/httpcall_common.js, line 49)

Send an HTTP GET request. Equivalent to calling HTTP.call with "GET" as the first argument.

Arguments

url String

The URL to which the request should be sent.

callOptions Object

Options passed on to HTTP.call.

asyncCallback Function

Callback that is called when the request is completed. Required on the client.

Anywhere

HTTP.post(url, [callOptions], [asyncCallback])

import { HTTP } from 'meteor/http' (http/httpcall_common.js, line 60)

Send an HTTP POST request. Equivalent to calling HTTP.call with "POST" as the first argument.

Arguments

url String

The URL to which the request should be sent.

callOptions Object

Options passed on to HTTP.call.

asyncCallback Function

Callback that is called when the request is completed. Required on the client.

Anywhere

HTTP.put(url, [callOptions], [asyncCallback])

import { HTTP } from 'meteor/http' (http/httpcall_common.js, line 71)

Send an HTTP PUT request. Equivalent to calling HTTP.call with "PUT" as the first argument.

Arguments

url String

The URL to which the request should be sent.

callOptions Object

Options passed on to HTTP.call.

asyncCallback Function

Callback that is called when the request is completed. Required on the client.

Anywhere

HTTP.del(url, [callOptions], [asyncCallback])

import { HTTP } from 'meteor/http' (http/httpcall_common.js, line 82)

Send an HTTP DELETE request. Equivalent to calling HTTP.call with "DELETE" as the first argument. (Named del to avoid conflict with the Javascript keyword delete)

Arguments

url String

The URL to which the request should be sent.

callOptions Object

Options passed on to HTTP.call.

asyncCallback Function

Callback that is called when the request is completed. Required on the client.