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's Mandrill 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
).
Methods
(static) download(url, downloadFile, config) → {HttpResponse}
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.
Parameters:
Name | Type | Description |
---|---|---|
url |
String | URL to send request to. |
downloadFile |
String | File | Download destination path or File object. |
config |
HttpConfiguration | Configuration for the request. |
Returns:
An object containing the response to the request.
- Type
- HttpResponse
(static) get(url, config) → {HttpResponse}
Gets data from the given URL. Query arguments may be provided in
the URL or in the params
field of the config
argument.
Parameters:
Name | Type | Description |
---|---|---|
url |
String | URL to post. |
config |
HttpConfiguration | Configuration for the request. |
Returns:
An object containing the response to the request.
- Type
- HttpResponse
(static) json(url, object, config) → {Object}
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..
Parameters:
Name | Type | Description |
---|---|---|
url |
String | URL to request from. |
object |
Object | Object to send. |
config |
HttpConfiguration | Configuration for the request. |
Returns:
The object that was JSON parsed from the body of the response.
- Type
- Object
(static) post(url, data, config) → {HttpResponse}
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 http.request below.
Parameters:
Name | Type | Description |
---|---|---|
url |
String | URL to post. |
data |
Object | Data to be posted. |
config |
HttpConfiguration | Configuration for the request. |
Returns:
An object containing the response to the request.
- Type
- HttpResponse
(static) request(method, url, data, config) → {HttpResponse}
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
isapplication/x-www-form-urlencoded
then the properties ofdata
will be encoded as the name-value pairs of a normal HTML form. -
If
contentType
isapplication/json
ordata
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 thecontentType
will be set totext/plain
,text/html
ortext/xml
, depending on whether or not the string appears to be HTML or XML
Parameters:
Name | Type | Description |
---|---|---|
method |
String | HTTP method to use. |
url |
String | URL to send request to. |
data |
Object | Data to send (if any). |
config |
HttpConfiguration | Configuration for the request. |
Returns:
An object containing the response to the request.
- Type
- HttpResponse