From MozillaWiki
< Labs‎ | Jetpack‎ | Reboot‎ | JEP
Jump to: navigation, search

JEP 109 - XHR

  • Champion: Myk Melez <>
  • Status: Accepted/Pre-Production
  • Bug Ticket: bug 547091
  • Type: API


Jetpack extensions should have a simple interface for making the common kinds of asynchronous network requests for which the XMLHttpRequest object is frequently used in both web content and traditional extensions.

The interface should permit cross-domain requests, which are often used by extensions. But it should not provide synchronous requests, which are uncommon, inconsistent with the asynchronous callback-based design of Jetpack APIs, and usually not actually synchronous (except possibly in the case of local file loads, for which a local file API should be used instead.

The first version of the interface should not provide the full configurability of XMLHttpRequest, although it may evolve to include more such functionality in the future. Its initial focus is the smallest set of features that satisfies the needs of the majority of users of XMLHttpRequest.

Use Cases

The primary use case is retrieving data from web services.

For example, an extension that provides access to your twitter stream might use this functionality to retrieve your stream from Twitter. And an extension that displays the weather might use it to retrieve data about the weather from Google's or Wunderground's web services.

A secondary use case is sending data to web services.

For example, that Twitter extension might allow you to input a new status that it then sends to Twitter.



The API is implemented by a Cuddlefish module named "request". The module exports the following symbols:

function; a constructor for Request objects


Request objects perform requests. They are configurable by setting their properties directly or passing a property collection as the options parameter of their constructors and methods.


The Request constructor has the following parameters:

a property collection that configures the object


String; the URL of the resource to request
Object; an unordered collection of name/value pairs representing headers to send with the request
Function; a callback function to call after the request is completed; is passed one parameter, response, which is a Response object
String; the content to send to the server
String (default: application/x-www-form-urlencoded); the type of the content to send to the server

If the content property is set to an object, it will be converted to a query string before being sent with the request. The content property is appended to the URL of a GET request and made the body of a POST request.

In the onComplete callback function, this is the Request object.


send the request using the HTTP GET method; accepts one parameter, options, a property collection that configures the request; returns the Request object
send the request using the HTTP POST method; accepts one parameter, options, a property collection that configures the request; returns the Request object


Request objects provide information about a server's response to a request. They are passed to a request's onComplete handler upon completion of the request.


String; the content of the response as plain text
DOMDocument; for XML responses (text/xml), the content of the response as a DOM document
Object; for JSON responses (application/json), the content of the response as JavaScript object
String; the HTTP response status code
String; the HTTP response status line
Object; the HTTP response headers

The xml and json properties should be lazily computed.


Get a web page and log it to the console:

const Request = require("request").Request;
new Request({
 url:       "",
 onComplete: function() console.log(this.response.text)