Requester
Script utility for handling data (typically JSON) from an external website. For the complete javadoc of the utility see Requester External link..
This utility supports the official request methods: GET, POST, HEAD, PUT, DELETE and PATCH, 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.
Supported options
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 |
GET
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) => {
...
});
PUT
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) => {
...
});
POST
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
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
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:
- First argument is the result - typically a JSON object.
- Second argument [@since Sitevision 4.2.3] is the statusCode - the http response status code.
- Third argument [@since Sitevision 4.5.1] is the headers - the http response headers.
Fail
Invoked when a Requester was unsuccessfully executed.
The callback is invoked with two optional arguments:
- First argument is the message - a string that describes the fail reason.
- Second argument [@since Sitevision 4.2.2] is the status - an object with four properties:
- statusCode - the http response status code. The value will typically be an official/RFC-standardized code (such as 400, 401, 404, 500 etc), but it can also be an unofficial/non-standardized one. A connection timeout will have value 1000 and the value will be 1001 if the connection pool is full/exhausted. An unknown/unspecified error will have value -1.
- statusMessage - the http response status code description.
- body [@since Sitevision 4.2.3] - the potential JSON body of the response. (Note! Will only be available for responses that specifies application/json in the Content-Type header)
- headers [@since Sitevision 4.5.1] - the potential response headers. (Note! Will only be available for valid error responses, not for request errors, JSON parse errors or such)
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) External link..