/**
* The `http` service allows scripts to make HTTP requests to other servers.
* It provides `get` and `put` functions for making GET and POST requests. If other
* types of requests are to be made then the `request` function should be used. The
* `json` function is a convenience method for making JSON-based POST requests.
*
* As an example, the following statement fetches the current EUR-USD exchange rate
* from `fixer.io`:
* ```
* var exchangeRate = http.json("http://api.fixer.io/latest?base=EUR").rates.USD;
* ```
* The `http.json` function parses the JSON data in the body of the response
* and returns it.
*
* The same tasks using `http.get` requires a bit more effort since the
* body of not automatically parsed:
* ```
* var fixerResult = http.get("http://api.fixer.io/latest?base=AUD");
* fixerResult = JSON.parse(fixerResult.body);
* var exchangeRate = fixerResult.rates.USD;
* ```
*
* The following statement sends a request to [MailChimp](https://mailchimp.com/)'s
* [Mandrill](http://www.mandrill.com/) service to send an e-mail message:
* ```
* http.json("https://mandrillapp.com/api/1.0/messages/send.json", {
* key: "ABC123def456ghi789",
* message: {
* html: "<h1>Test message</h1>",
* text: "Test message",
* subject: "Test message",
* from_email: "sender@test.com",
* from_name: "Ms Sender",
* to: [
* {
* email: "recipient@test.com",
* name: "Mr Recipient"
* }
* ]
* }
* });
* ```
* The second argument is a Javascript object, which the `http.json` function
* stringifies and sends in the body of the request. It also sets the `ContentType`
* to the type required for JSON requests (i.e. `application/json`).
* @namespace
*/
var http = {
/**
* Gets data from the given URL. Query arguments may be provided in
* the URL or in the `params` field of the `config` argument.
* @method
* @param {String} url URL to get.
* @param {HttpConfiguration} config Configuration for the request.
* @return {HttpResponse} An object containing the response to the request.
*/
get: function (url, config) { },
/**
* Posts the given data to the given URL. Query arguments may be provided in
* the URL or in the `params` field of the `config` argument. The body of the request is provided in the
* `data` argument as described in {@link http.request} below.
*
* @method
* @param {String} url URL to post.
* @param {Object} data Data to be posted.
* @param {HttpConfiguration} config Configuration for the request.
* @return {HttpResponse} An object containing the response to the request.
*/
post: function (url, data, config) { },
/**
* Sends a request using the given method to the given URL.
*
* Query arguments may be provided in
* the URL or in the `params` field of the `config` argument.
*
* For example, a Google search for the term 'hello' would be performed as follows:
* ```
* var result = http.get('https://www.google.com.au/search', {
* params: {
* q: "hello"
* }
* });
* ```
* This is equivalent to the entering the following URL in a browser.
* ```
* https://www.google.com.au/search?q=hello
* ```
*
* The data to be sent is provided in the `data` argument. The way in which
* it is sent depends on its type and on the value of the `contentType` argument.
*
* * If `contentType` is `application/x-www-form-urlencoded` then the
* properties of `data` will be encoded as the name-value
* pairs of a normal HTML form.
*
* * If `contentType` is `application/json` or
* `data` is an object, a number or a boolean, then it will be JSON stringified.
*
* * If it is a string then and the content type is not `application/json`
* then the `contentType` will be set to `text/plain`, `text/html` or
* `text/xml`, depending on whether or not the string appears to be HTML or
* XML
*
* @method
* @param {String} method HTTP method to use.
* @param {String} url URL to send request to.
* @param {Object} data Data to send (if any).
* @param {HttpConfiguration} config Configuration for the request.
* @return {HttpResponse} An object containing the response to the request.
*/
request: function (method, url, data, config) { },
/**
* Makes a JSON-based POST request to the given URL. The `object` argument will
* be JSON stringified and sent in the body. The content-type will be set to
* `application/json`. The response will be assumed to be JSON and will be
* parsed and returned from the function. Query arguments may be provided in
* the URL or in the `params` field of the `config` argument..
*
* @method
* @param {String} url URL to request from.
* @param {Object} object Object to send.
* @param {HttpConfiguration} config Configuration for the request.
* @return {Object} The object that was JSON parsed from the body of the response.
*/
json: function (url, object, config) { },
/**
* Downloads a file from the given URL to the given path in the virtual file-system.
*
* The destination of the file to be downloadloaded is provided in the
* `downloadFile` argument.
* It must either be a string representing the path of the file or a File object.
*
* @method
* @param {String} url URL to send request to.
* @param {String|File} downloadFile Download destination path or File object.
* @param {HttpConfiguration} config Configuration for the request.
* @return {HttpResponse} An object containing the response to the request.
*/
download: function (url, downloadFile, config) { }
}
/**
* Encapsulates the response to a HTTP request.
* @typedef {Object} HttpResponse
* @property {String} body The body of the response
* @property {HttpResponseStatus} status The response code and its description
*/
/**
* Encapsulates the status of an HTTP response
* @typedef {Object} HttpResponseStatus
* @property {number} code The response code
* @property {String} description The response description
*/
/**
* Configuration of HTTP request
* @typedef {Object} HttpConfiguration
* @property {Object} params Query arguments. These may alternatively be included in the `url` argument.
* @property {Number} timeout Timeout in milliseconds.
* @property {Object} headers HTTP headers.
* @property {Object} contentType MIME type.
*/