Labs/Jetpack/Reboot/JEP/109
Contents
JEP 109 - XHR
- Champion: Myk Melez <myk@mozilla.org>
- Status: Accepted/Pre-Production
- Bug Ticket: bug 547091
- Type: API
Introduction
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.
Implementation
Module
The API is implemented by a Cuddlefish module named "request". The module exports the following symbols:
- Request
- function; a constructor for Request objects
Request
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.
Constructor
The Request constructor has the following parameters:
- options
- a property collection that configures the object
Properties
- url
- String; the URL of the resource to request
- headers
- Object; an unordered collection of name/value pairs representing headers to send with the request
- onComplete
- Function; a callback function to call after the request is completed; is passed one parameter,
response, which is a Response object - content
- String; the content to send to the server
- contentType
- 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.
Methods
- get
- send the request using the HTTP GET method; accepts one parameter,
options, a property collection that configures the request; returns the Request object - post
- send the request using the HTTP POST method; accepts one parameter,
options, a property collection that configures the request; returns the Request object
Response
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.
Properties
- text
- String; the content of the response as plain text
- xml
- DOMDocument; for XML responses (text/xml), the content of the response as a DOM document
- json
- Object; for JSON responses (application/json), the content of the response as JavaScript object
- status
- String; the HTTP response status code
- statusText
- String; the HTTP response status line
- headers
- Object; the HTTP response headers
The xml and json properties should be lazily computed.
Examples
Get a web page and log it to the console:
const Request = require("request").Request;
new Request({
url: "http://example.com/",
onComplete: function() console.log(this.response.text)
}).get();
