HTTP

Documentation of Meteor's HTTP API.

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

meteor add http

Anywhere

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

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

Perform an outbound HTTP request.

Arguments

• methodString

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

• urlString

• The URL to retrieve.

• asyncCallbackFunction

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

Options

• contentString

• String to use as the HTTP request body.

• dataObject

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

• queryString

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

• paramsObject

• 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.

• authString

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

• headersObject

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

• timeoutNumber

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

• followRedirectsBoolean

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

• npmRequestOptionsObject

• 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.

• beforeSendFunction

• 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 sent.

This function initiates an HTTP request to a remote server.

On the server, this function can be run either synchronously orasynchronously. If the callback is omitted, it runs synchronouslyand the results are returned once the request completes successfully.If the request was not successful, an error is thrown.This isuseful when making server-to-server HTTP API calls from within Meteormethods, as the method can succeed or fail based on the results of thesynchronous HTTP call. In this case, consider usingthis.unblock() to allow other methods on the sameconnection to run inthe mean time.

On the client, this function must be used asynchronously by passing a callback. Note that some browsers first send an OPTIONS request before sending your request (in order todetermine CORS headers).

Both HTTP and HTTPS protocols are supported. The url argument must bean absolute URL including protocol and host name on the server, but may berelative to the current host on the client. The query optionreplaces the query string of url. Parameters specified in paramsthat are put in the URL are appended to any query string.For example, with a url of '/path?query' andparams 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 thetype of request. In the case of request with no bodies, like GET andHEAD, the parameters will always go in the URL. For a POST or othertype of request, the parameters will be encoded into the body with astandard x-www-form-urlencoded content type, unless the contentor data option is used to specify a body, in which case theparameters will be appended to the URL instead.

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

Contents of the result object:

• statusCodeNumber
• Numeric HTTP result status code, or null on error.
• contentString
• The body of the HTTP response as a string.
• dataObject or null
• If the response headers indicate JSON content, this contains the body of the document parsed as a JSON object.
• headersObject
• A dictionary of HTTP headers from the response.

Example server method:

Meteor.methods({
  checkTwitter(userId) {
    check(userId, String);
    this.unblock();
    try {
      const result = HTTP.call('GET', 'http://api.twitter.com/xyz', {
        params: { user: userId }
      });
      return true;
    } catch (e) {
      // Got a network error, timeout, 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 }
}, (error, result) => {
  if (!error) {
    Session.set('twizzled', true);
  }
});

Anywhere

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

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

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

Arguments

• urlString

• The URL to which the request should be sent.

• callOptionsObject

• Options passed on to HTTP.call.

• asyncCallbackFunction

• 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 64)

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

Arguments

• urlString

• The URL to which the request should be sent.

• callOptionsObject

• Options passed on to HTTP.call.

• asyncCallbackFunction

• 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 75)

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

Arguments

• urlString

• The URL to which the request should be sent.

• callOptionsObject

• Options passed on to HTTP.call.

• asyncCallbackFunction

• 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 86)

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

• urlString

• The URL to which the request should be sent.

• callOptionsObject

• Options passed on to HTTP.call.

• asyncCallbackFunction

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