Script utility for handling data (typically JSON) from an external website.
This utility supports the official request methods: GET, POST, HEAD, PUT and DELETE, but not the OPTIONS method or the idempotent TRACE method. Redirects will only be followed for the GET and HEAD methods.
URL:s with an international domain name (IDN) will be converted (ACE:d) automatically internally by this utility, e.g. invoking get("http://www.ringsjömingel.se") will do a HTTP GET using "http://www.xn--ringsjmingel-9ib.se".
Below is a example of how to use the Requester utility to execute a basic GET and process the JSON response body.
requester = require('Requester')
Property | Descripion | Type | Default | Since |
---|---|---|---|---|
data | Request parameters. | key/value | ||
contentType | Request data type.
| string | application/x-www-form-urlencoded | |
headers | Request headers. Note that the Content-Type header is automatically set for "multipart/form-data" requests | key/value | ||
username | The username to use for authentication | string | ||
password | The password to use for authentication | string | ||
preemptiveAuthentication | Whether or not to do a preemptive BASIC authentication | boolean | false | |
dataType | Response data type
| string | json | |
files | Files to include when using "multipart/form-data" as contentType. Value must be a Node of type sv:file, sv:temporaryFile or sv:image. | key/value | 4.5.4 |
A basic GET-request. Returns a chainable requester.
requester.get('example url')
.done(result => {
...
})
.fail((message, status) => {
...
});
GET-request with options
const options = {
username: 'klinsmann',
password: 'klinsmann_123',
preemptiveAuthentication: true,
headers: {
'X-custom-header': 'Custom value'
},
data: {
query: 'football',
category: 'all'
}
};
requester.get('https://arestfulsite.se/search', options)
.done((result, statusCode, headers) => {
// GET succeeded, handle potential JSON response result appropriately
if (statusCode === 204) {
...
} else {
...
}
...
})
.fail((message, status) => {
// GET failed, handle appropriately
if (status.statusCode === 401) {
...
}
if (status.headers) {
...
}
if (status.body) {
...
}
...
});
Get and store a file in specific folder in Sitevision file archive
...
requester = require('Requester'),
fileUtil = require('FileUtil'),
resourceLocatorUtil = require('ResourceLocatorUtil');
...
const multipartOptions = {
dataType: 'file',
}
requester.get('https://getfileexample/test', multipartOptions)
.done((data, statusCode) => {
if (statusCode === 200) {
// Use resourceLocatorUtil to get the site file repository
var fileRepository = resourceLocatorUtil.getFileRepository();
// Retrieve folder to store your file by relative path
var folder = fileRepository.getNode('TestFolder')
// Use fileUtil to create a file from temporary file
// Returns new fileNode
fileUtil.createFileFromTemporary(folder, data);
}
})
.fail((message, status) => {
...
});
A basic PUT-request.
const options = {
data: {
name: 'Jane Doe'
}
};
requester.put('https://arestfulsite.se/endpoint/update', options)
.done((data, statusCode, headers) => {
...
})
.fail((message, status) => {
...
});
A basic POST-request.
const multipartOptions = {
contentType: 'multipart/form-data',
files: {
file: fileNode, // sv:file, sv:temporaryFile or sv:image
},
data: {
name: 'foo'
}
};
requester.post('https://arestfulsite.se/endpoint', multipartOptions)
Delete specific options:
Property | Description | Type | Default | Since |
---|---|---|---|---|
deleteOptions | Options for delete
| key/value | 4.5.3 |
A basic DELETE-request.
const options = {
data: {
id: 'abc_123'
}
};
requester.delete('https://arestfulsite.se/endpoint/delete', options)
.done((data, statusCode, headers) => {
...
})
.fail((message, status) => {
...
});
Chainable request is the result of a Requester invocation.
Done
Invoked when a Requester was successfully executed. The callback is invoked with three optional arguments:
Fail
Invoked when a Requester was unsuccessfully executed.
The callback is invoked with two optional arguments:
Note that outgoing socket connections is a shared (and limited) server resource! All requests will be handled by connections that comes from a shared http connection pool. The pool has a fixed number of connections (typically 100) and specified timeouts (typically 5 seconds). A request will fail if a connection can not be made at all (exhausted pool) or if the external website doesn't respond in time (request timeout). A failure is typically handled via RequesterChainable.fail(Object).