Requester

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')

Supported options

Property

Descripion

Type

Default

Since

data

Request parameters.

key/value



contentType

Request data type.

  • "text/plain" - data will be sent as a string entity
  • "application/json" - data will be sent as JSON
  • "multipart/form-data" [@since Sitevision 4.5.4] - request will be sent as multipart form entity

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

  • "json" - response body will be parsed as JSON
  • "xml" - response body will be converted to and parsed as JSON
  • "text" [@since Sitevision 4.2.3] - response body will be as-is (i.e. plain text string)
  • "file" [@since Sitevision 4.5.5] - response body will be a binary file wrapped as a sv:temporaryFile

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

  • sendDataAsBody (boolean) - Send data in the request body

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).