Call REST

The call REST action is used to make a REST call in conjunction with the service definitions.

Internally, this action uses the REST Helper, which is a public utility. Its parameters are as follows.

Parameter Name	Description
endpoint	The endpoint ID as defined in the service configuration.
uriParams	A key/value pair map that will be used to override path and query parameters as defined in the service endpoint.
body	A structured object that will be sent as the body.
requestType	The content-type of the request, either 'json', 'form', or 'url'. Note: Note that this is deprecated. Instead, use 'contentType' and 'fileContentType'.
headers	An object; each property name is a header name and value that will be sent with the request.
contentType	An optional string value with an actual MIME type, which will be used for the "content-type" header. When used with "fileContentType", this is also used as the type for the File blob.
responseType	If set, the specified type is used to do two things at run-time: Generate a fields parameter for the REST URI to limit the attributes fetched; Automatically map the fetched response to the response type (when used with the built-in vb/BusinessObjectsTransform). This applies to standard action chains. See the definition for "responseType" in Service Data Provider Properties for details on how the assigned type is used in that context.
filePath	An optional path to a file to send with the request. If "contentType" is set, that is used as the type for the File contents. If “contentType” is not set, a lookup of common file extensions will be used.
filePartName	Optional, used with filePath to allow override of the default name ("file") for the FormData part.
fileContentType	An optional string, used in combination with "contentType", "multipart/form-data", and "filePath".
hookHandler	Used primarily by vb/ServiceDataProvider when externalizing data fetches. See Service Data Provider for details.
requestTransformOptions	A map of values to pass to the corresponding transform, as the "options" parameter.
requestTransformFunctions	A map of named transform functions, called before making the request, where the function is: fn(configuration, options)
responseTransformFunctions	A map of named transform functions, called before making the response, where the function is: fn(configuration, options)
responseBodyFormat	A string that allows an override of the standard Rest behavior, which normally looks for a “content-type” header to determine how to read and parse the response. Possible values are "text", "json", "blob", "arrayBuffer", "base64", "base64Url", and "formData".
responseFields	This is an "advanced" field, for use specifically with JET Dynamic Forms. The value would typically be a variable that is bound to the <oj-dynamic-form> "rendered-fields" attribute. This is how a calculated layout can tell the Rest Action call which fields to fetch. Note: The vb/BusinessObjectsTransform transform is necessary to create a query from this value. Note: When "responseFields" is provided, "responseType" is ignored.

Using multipart/form Data

If you have set "contentType" to "multipart/form-data", the Call REST action interprets your request "body" object as the form parts. Each property of the body object is a form part, which is a key-value pair with its own content type and disposition.

If "filePath" is also set, it is added as an additional part using the lookup of common file extension types.

If "filePath" is also set, it is added as an additional part using the sample simple file extension type association. The name of this part is "file", or can be specified using "filePartName".

You may optionally override the file type by using "fileContentType" for the file part.

For more about working with the multipart/form-data format, refer to this Oracle blog, Consuming REST APIs in VB - multipart/form-data.

Parameters Typically Required per Endpoint Type

These are the typically required parameters for each endpoint type:

• POST:
  • body parameter is set to the variable containing the new record's data.
  • uriParams parameter is used to provide any required input parameters.

  Here's an example POST endpoint call:

        const callRestCreateIncident = await Actions.callRest(context, {
          endpoint: 'fixitfast/putIncident',
          body: $page.variables.incidentPayload ,
          uriParams: {
            id: $page.constants.incidentId,
          },
        });

• GET:
  • uriParams parameter is used to provide any required input parameters, such as an ID input parameter to get a single record.

    Here's an example of a GET endpoint call to get a single record. The empIDToGet_ip variable is an input parameter that passes the record's ID to the action chain that contains this Call REST call:

          const getEmployeeResult = await Actions.callRest(context, {
            endpoint: 'businessObjects/get_Employee',
            uriParams: {
              'Employee_Id': empIDToGet_ip,
            },
          });

• DELETE:
  • uriParams parameter is used to provide the ID of the record to delete.

    Here's an example of a DELETE endpoint call to delete a record. The empIDToDelete_ip variable is an input parameter that passes the record's ID to the action chain that contains this Call REST call:

          const callRestBusinessObjectsDeleteEmployeeResult = await Actions.callRest(context, {
            endpoint: 'businessObjects/delete_Employee',
            uriParams: {
              'Employee_Id': empIDToDelete_ip,
            },
          });

• PATCH:
  • body parameter is set to the variable containing the record with the updated data.
  • uriParams parameter is used to provide the ID of the record to update.

  Here's an example PATCH endpoint call:

        const updateEmployeeResult = await Actions.callRest(context, {
          endpoint: 'businessObjects/update_Employee',
          uriParams: {
            'Employee_Id': $page.variables.empID_pv,
          },
          body: $page.variables.EmpUpdatedData_pv,
        });

Service Definitions

If your service connection details are static, the details, such as the server, path, and schema of the request and response, are stored in the openapi3.json file for the service connection.

To view or edit a service's definition, select the service connection in the Services pane, then open the Source tab. The editor uses the OpenAPI3 specification and JSON format.

Description of the illustration jsac-service-connection-source-tab.jpg

Transforms

The requestTransformOptions, requestTransformFunctions, and responseTransformFunctions can be used to modify the request and response. Some built-in service endpoints have built-in transform functions for 'sort', 'filter', 'paginate', and 'select', so options for these transform functions can be defined using the same name via the requestTransformOptions property. For third party services, the options set are based on the type of transform functions supported.

When using the Rest Action the transform names have no semantic meaning, and all request and response transforms are called.

Request and response transform functions have the following signatures.

Transform Type	Parameters	Return Value
Request	/** * configuration: { * url: * initConfig: { * method: // string with http method * body: // request body, if any * credentials: // string see (fetch) Request * headers: // object, map of strings * } * }, * * options: provided by the application * * context: an empty object, which exists for the * lifetime of one REST call, a set of * transforms share this. **/ mytransform(configuration, options, context)	Configuration object; see "Parameters". Typically, returns the same object passed in, or a modified one.
Response	/** * response: { body, headers } * * context: an empty object, see "Request transforms" * */ myresponsetransform(response, context);	The return value is application-defined. The value is returned as the 'transformResults' of the REST call result: /** * { * response: The (fetch) Response object. Note that the body has already * been read, so the functions (ex. json()) cannot be called. * * body: the result of the json()/text()/etc. * * transformResults: a map of return values from Response Transforms * } */

Example 1-17 A Simple Transform Function

One request transform function and one response transform function for a third party service or endpoint might look like this example. Here, the transform functions are defined in the page module and are configured on the RestAction directly. More commonly, transform functions are defined in the service definition and do not need to be mapped on the RestAction.

"fetchIncidentList": {
  "module": "vb/action/builtin/restAction",
  "parameters": {
    "endpoint": "ifixitfast-service/getIncidents",
    "requestTransformOptions": {
      "sort": "{{ $page.variables.sortExpression }}",
    },
    "requestTransformFunctions": {
      "sort": "{{ $page.functions.sort }}"
    },
    "responseTransformFunctions": {
      "paginate": "{{ $page.functions.paginateResponse }}"
    }
  },
  "outcomes": {
    "success": "returnSuccessResponse",
    "failure": "returnFailureResponse"
  }
},

The corresponding module functions would be:

PageModule.prototype.sort = function (configuration, options) {
   /// some code here to modify 'configuration'
   return configuration;
}

PageModule.prototype.paginateResponse = function (configuration) {
   /// some code here to modify 'configuration'
   return configuration;
}

Error Handling and Return Values

If the underlying REST API request returns a status code, the error object is returned for you to handle the error yourself, otherwise an auto-generated error notification is shown.

The object returned by the Call REST action returns these results:

Result	Relevant Properties of Returned Object	Returned Object
Success	If the returned object’s ok property is set to true, indicating success, these are the object’s relevant properties: body: object with results from the call (scalar, object, array, etc.) headers: Headers object ok: boolean, set to true status: number, set to 200 statusText: string, set to "OK"	{ body {}, error: null, headers: Headers {}, message: {summary: ‘ ’}, ok: true, status: 200 statusText: "OK", } *If a single record is returned, it is contained in the body{} object; if multiple records are returned, they are contained in the body{} object’s results parameter.
Error	If the returned object’s ok property is set to false, indicating failure, these are the object’s relevant properties: error: error object or null message: object with error summary ok: boolean, set to false status: number statusText: string showing type of error	{ body: null, error: null, headers: Headers {}, message: {summary: ‘<error summary>’}, ok: false, status: <status number>, statusText: ‘<error type>’ }

For details about working with business objects, refer to Accessing Business Objects Using REST APIs.