|
Version1 /
http-client ModuleLibrary for making HTTP requests. Cross-origin requests are generally prohibited for scripts (and, therefore, accessors) running in a browser. See Browser Considerations for details. API
In all cases, the first argument is either a string with a URL or a JavaScript object with a number of fields defined below. Also, in all cases, the responseCallback function, if provided, will be called when the request has been fully satisfied. The responseCallback function will be passed one argument, an instance of the IncomingMessage class, defined below. The difference between request() and the other functions is that the former only begins the interaction with the server, whereas the rest are complete, self-contained requests. Specifically, if you use request, you can use the returned object to send additional information to the server, for example to PUT a file on the server. Both functions return an instance of the ClientRequest class, defined below. UsageA simple use to read the contents of a web page looks like this:
var http = require('@accessors-modules/http-client');
http.get('http://ptolemy.eecs.berkeley.edu', function(response) {
console.log('Got response: ' + response.body);
});
To view all returned parameters from http.get():
var http = require('@accessors-modules/http-client');
http.get('http://ptolemy.eecs.berkeley.edu', function(response) {
console.log('Got response: ' + JSON.stringify(response));
});
POST and PUT requests typically specify a body, using options.body. (This URL will give an error since it doesn't allow posting).
var http = require('@accessors-modules/http-client');
var options = {
body : {test : 'this is a test'},
url : 'http://ptolemy.eecs.berkeley.edu'
};
http.post(options, function(response) {
console.log('Got response: ' + JSON.stringify(response));
});
OptionsThe options argument to the above functions can be a string URL or a JavaScript object with the following (optional) fields:
IncomingMessageThe responseCallback function, if provided, will be passed an instance of IncomingMessage, which has these fields:
FIXME: At this time, only UTF-8-encoded string bodies are supported. Also, by including the body of the response in the argument to the callback, rather than a socket, we limit the size of the body. A large response (e.g. a video file) could easily overwhelm available RAM memory. ClientRequestThe request and get functions both return an instance of ClientRequest, which has the following functions:
The ClientRequest class is an event emitter that emits the following events:
Browser ConsiderationsCross-Origin RequestsFor security reasons, scripts in a browser are generally prohibited from certain types of data transfer in cross-origin requests. The same-origin policy states that two pages have the same origin if the protocol, port (if given), and host are the same for both pages. Client-server coordination is required to achieve cross-origin communication. Two techniques are cross-origin resource sharing (CORS) and JSON with padding (JSONP). Cross-Origin Resource Sharing (CORS)A server may stipulate that cross-origin requests are allowed. This is called cross-origin resource sharing (CORS).
Origin: http://www.terraswarm.org A server sets the response header Access-Control-Allow-Origin : * or Access-Control-Allow-Origin : http://www.terraswarm.org The client checks this header. If access is allowed, the content is loaded.
JSON with padding (JSONP)The JSON with padding technique takes advantage of the fact that <script src="http://www.otherdomain.com/thescript.js"> </script> In a JSONP request, the client specifies some text to pre-pend to a JSON response. The server replies with the text plus the JSON data enclosed in parenthesis. If the client defines a function locally and sends the function name as the text, this function is then executed with the JSON data as an argument. For example, calling http://ip.jsontest.com/ will return your IP address in JSON form. Example:
{"ip": "8.8.8.8"}
A client could define a function that displays data:
function showIP(data) {
alert(data);
}
Next, the client asks the server to prepend this function name to the returned JSON by appending
showIP({"ip": "8.8.8.8"});
The jQuery's
jquery.getJSON("http://jsonplaceholder.typicode.com/posts/1?callback=?", function(data) {
console.log(JSON.stringify(data));
});
Here's another example. APIs and LibrariesXMLHttpRequestXMLHttpRequest is an API that allows a client to fetch and send data without having to do a full page refresh. All modern browsers (Chrome, IE7+, Firefox, Safari, and Opera) include a built-in XMLHttpRequest implementation. XMLHttpRequest supports:
Please see Mozilla's XMLHttpRequest for a complete list of methods and browser support, and Using XMLHttpRequest for examples. jQueryjQuery is a "fast, small, and feature-rich JavaScript library" that is supported by modern browsers. jQuery defines an easy-to-use API for common HTML manipulation and data transfer tasks. jQuery includes an AJAX (Asynchronous Javascript and XML) method that wraps XMLHttpRequest for issuing requests. There is also a shorthand GET method. BrowserifyBrowserify is a bundling system and set of modules that replicates most node.js APIs and functionality in a browser. Browserify allows one to use the "requires" syntax in a browser and creates a bundle of all modules needed for a particular piece of code by collecting all of the "require" dependencies. For example: browserify main.js > bundle.js will recursively locate all dependencies starting in the <script src="bundle.js"> </script> Browserify includes both HTTP and HTTPS modules. These modules depend on many others, so accessors that use browserify would need to either include bundles or have the browserify source code available in the accessor repository or other location. jQuery-browserifyThere is a browserify version of jQuery, jQuery-browserify. Unfortunately, jQuery-browserify has no license, so the terms of use are unknown. See AlsoBack to Optional JavaScript Modules |