modules:rest

REST Module

Function

This module enables users to integrate with a REST webservice from within an application. It is necessary to already have a REST webservice created. The REST URL goes in the appropriate field in the module.

There are five different HTTP request types available in the module.

  • GET
  • POST
  • POST RAW
  • PUT
  • DELETE

Using a GET simply makes a request of the REST webservice. The POST, POST RAW, and PUT options all enable users to send a variable from Fuse and send it to a webserver. The webserver then returns data, which is available within Fuse as a subvariable for that module. Users can branch the call-flow based on variables returned by a webservice.

The POST option generates a field in the module that allows users to input a variable and a value to assign it.

The POST RAW and PUT options both generate a text box where users enter RAW POST or RAW PUT data.


Inputs

The REST module has multiple input options.

URL

The URL where the webservice request is made.

Headers

Optional input whereby requests include HTTP which is enabled by the Show Headers setting

Return Type

This defines the expected response format. Fuse will attempt to parse returned data based on this value.
Available options are: JSON, CSV, XML, TEXT, or EMPTY (if a request does not return a response body).

In order to access all data within the response properly, it is recommended to use the JSON format as data within can be accessed using the dot notation easily.


JSON

Data inside JSON responses from the REST module are returned as an object and can be accessed using dot notation.
Consider the following example:



JSON Response

{ 
    "status": "success",
    "data": {
        "name": "John Smith",
        "age": 30,
        "balance": 20.00,
        "vehicles": [
            { "make": "Ford", "year": 2016 },
            { "make": "Chevrolet", "year": 2012 }
        ]
    }
}

Fuse+ Variable

Variable Value
request.status success
request.data.name John Smith
request.data.age 30
request.data.balance 20.00
request.data.vehicles.length 2
request.data.vehicles[0].make Ford




CSV

The modules expects CSV responses to have columns defined in the first row, so that the data can be accessed with the column names.



city,state,metro population
Chicago,Illinois,9551031
Houston,Texas,6656947
Los Angeles,California,13340068
New York,New York,20182305
Variable Value



XML

While Fuse can handle XML response as they are converted into javascript objects, it is still recommended that the JSON format be used over XML due to some limitations on how the data can be transformed.

See the following example.



XML Response:

<?xml version="1.0" encoding="UTF-8"?>
<lunch_menu>
  <entree type="sandwich">
    <name>Grilled Chicken Sandwich</name>
    <price>$8.95</price>
  </entree>
  <entree type="sandwich">
    <name>Meatball Sandwich</name>
    <price>$8.95</price>
  </entree>
  <entree type="pasta">
    <name>Bolognese</name>
    <price>$9.95</price>
  </entree>
</lunch_menu>

Fuse Converted JS Object

{
  "entree": [
    {
      "@attributes": {
        "type": "sandwich"
      },
      "name": "Grilled Chicken Sandwich",
      "price": "7.95"
    },
    {
      "@attributes": {
         "type": "sandwich"
      },
      "name": "Meatball Sandwich",
      "price": "8.95"
    },
    {
      "@attributes": {
        "type": "pasta"
      },
      "name": "Bolognese",
      "price": "9.95",
    },
  ]
}

Variable Value
request_xml.entree.length 3
request_xml.entree[0].name Grilled Chicken Sandwich
request_xml.entree[2].price 9.95
type (see right example) pasta

Nodes in the XML can be accessed with dot notation.


XML attributes, on the other hand, is a bit more complexed to avoid potential naming conflicts.
Attributes have to accessed via the Evaluate JS ( ) module in Fuse.
See the following:





Note: Because of the way that the XML data is converted into a javascript object, certain data element might be lost during this process.
For example, any attribute that exist in a leaf text node will not be available.

For the full detail of how the XML request is converted, please refer to the call log, under “Response” tab of the REST request.



Text

This allows the variable to set its entirety to the text that is returned from the request.



Empty

This setting will just ignore any response (even if it is a valid format JSON for example) from the web server and the variable will be empty regardless of what was returned.


POST RAW/PUT Body

The POST RAW and PUT options both generate a text box where users enter RAW POST or RAW PUT request body. If using JSON, be sure to include a 'Content-Type: application/json' header so the webservice knows to expect a JSON body.

Note: All of the REST module's input fields can accept variables that exist within the current application.


Module Settings

Hold Music

Enable this setting to play audio while an end-user is on hold.
To upload a file for hold music, go to Application Settings > Connection Settings > Webservices > Webservice fetch audio.

Timeout Length

This allows users to set the maximum time, in seconds, that elapse before returning a timeout error. This applies modules that fetch outside scripts, like the SOAP, REST, or subdialog modules.

The default value for Timeout Length is 30 seconds.
Acceptable number values range from 1 to 120.

Private

This setting controls the logging function of a module.
Enabling the 'Private' setting instructs the module to not record, report, or retain the information input to that module for reporting or any other purposes. When enabled any information entered into a module during a call will be lost immediately when the call terminates.
The 'Private' setting is critical for businesses that need to maintain PCI-DSS or HIPAA compliance.

The module icon, in the upper left-hand corner, becomes grayed-out when this setting is enabled. See more details here.

Show Headers

Enabling it generates a field in the module that allows users to enter custom headers for REST webservice requests.
Each header should be on a separate line with the header name and associated value separated by a colon.

Show Custom Errors (REST)

This setting can be used to catch any error that occur with the REST call.
It can be used to branch off non-2XX responses from the web server.

To get the exact HTTP response code from the request, please refer to the Shadow Variables section.

Additional Info

Advanced Settings: Advanced Fuse users may want to use shadow variables that are available with the REST module. For more information on this functionality, please visit the Shadow Variables page.

SMS: At this time, it's possible to send and receive SMS messages using the REST module in Fuse+ and Plum's SMS API in Plum DEV. For more information about the SMS API see the DEV documentation for inbound and outbound SMS.
Note: Using the SMS API requires an active Plum DEV account. Contact your account manager for more information.

modules/rest.txt · Last modified: 2019/01/10 19:59 by admin