REST Helper

The REST helper utility allows calling REST endpoints, which are defined in the service definitions.

The Visual Builder runtime uses this helper internally.

The REST helper looks at the content-type header, if available, to try to determine how to read and parse the response. If no content-type is available, text is assumed.

Table 1-3 REST helper content types

Content type	Response method
contains "json"	Response.json()
starts with "image/"	Response.blob()
application/octet-stream	Response.blob()

This behavior can be overridden using the responseBodyFormat() method.

Here's an example of how to use of the REST helper:

define(['vb/helpers/rest'], (Rest) => { 
...
async callRestViaHelper() {
    const myparameters = { qparam1 : “value1”, qparam2 : “value2” } ;
    // parameter info will be appened to endpoint URL using this format: ?qparam1=value1&qparam2=value2
    const rest = Rest.get('myservice/myendpoint').parameters(myparameters);
    const result = await rest.fetch();
    return result.body;
}

Here's a snippet showing how to use the REST helper with an extension, with the second parameter defining the scope:

define(['vb/helpers/rest'], (Rest) => { 
...
async callRestViaHelper () {
    const rest = Rest.get('serviceExtensionId:serviceId/endpointId', {extensionId:myExtensionId});
    const result = await rest.fetch();
}

In this example, a header is passed to the REST helper:

define(['vb/helpers/rest'], (Rest) => { 
...
async callRestViaHelper () {
    const initConfig = { headers : { someHeader : “abc”  } } ;   
    // add a header called “someHeader” with value “abc”  
    var const rest = Rest.get('myservice/myendpoint').initConfiguration(initConfig);
    var const result =await  rest.fetch();
}

If the header has hyphens, create the initConfig object like this:

// add a header called “x-dynamic-header” with value “def”
const initConfig = { headers : { ["x-dynamic-header"] : "def" } };

Table 1-4 REST helper methods

Method	Parameters	Return Value	Description
static get(endpointId)	endpointId: serverID/operationID, same as RestAction, ServiceDataProvider	Instance of REST object	Factory method
initConfiguration(initConfig)	initConfig: the initConfig of the fetch() Request object	REST helper, to allow chaining of method calls	See the Request Web API
parameters(parametersMap)	parametersMap: object of key/value pairs, same as RestAction 'uriParams'	REST helper	Set the parameter for the call. Parameters defined as path parameters for the endpoint will be inserted in the URL as appropriate; the rest will be appended as query parameters.
requestTransformationFunctions (transformationFunctionMap)	transformationFunctionMap: map of functions.	REST helper	See Call REST Action
requestTransformationOptions (transformationOptionMap)	transformationOptionMap: map of request transform parameters	REST helper	See Call REST Action
responseTransformationFunctions (transformationFunctionMap)	transformationFunctionMap: map of functions.	REST helper	See Call REST Action
body(body)	body: actual payload to send with the request	REST helper	-
hookHandler(handler)	handler: should extend RestHookHandler, and may override the following: handlePreFetchHook(rest) handleRequestHook(request) -returns request handleResponseHook(response) -returns response handlePostFetchHook(result) handlePostFetchErrorHook(result)	REST helper	Allows installation of callbacks for various phases of the REST call, which may configure the REST helpers, modify the request and response, or do special processing based on the result or result error. define(['vb/helpers/rest', 'vb/helpers/rest'], (Rest, RestHookHandler) => { class MyHandler extends RestHookHandler {
responseBodyFormat(format)	format: one of: text, json, blob, arrayBuffer, base64, or base64Url. The response body type is the same as the corresponding method for Response (except base64, which returns just the encoded portion of the base64 URL).	REST helper	Overrides the default behavior, which looks at the "content-type" header to determine how to read (and parse) the response.
fetch()	-	Promise	Performs the configured fetch() call
toUrl() toRelativeUrl()	-	Promise	Utility methods for building requests and responses that require the endpoint path. Resolves with the full (or relative) path of the endpoint, or empty string if the endpoint is not found.

The REST helper fetch() call returns a Promise that resolves with an object that contains the following properties:

Table 1-5 fetch() call return value

Property	Description
response	The Response object from the native fetch() call, or the return from a HookHandler's handleResponseHook, if one is being used.
body	The body of the response object; the helper will attempt to call the appropriate Response method (json(), blob(), arrayBuffer(), etc) based on responseBodyFormat() and Content-Type.