REST Service Integration Overview

Overview

The REST Service holds the configuration data which is shared between all calls to a service, including the base URL, authentication, and any custom headers. This service acts as a folder, holding any number of REST Methods. Each REST Method defines an HTTP call that can be made to the URL defined in the REST Service.

Creating a REST Service

To create a REST Service navigate to System > Integration > External Services, select Add REST Service in the bottom action panel.

After entering a service URL, the Ping Result field will show the result of trying to reach that URL.
Braces can be used to define variables within the URL. These variables will appear as flow step inputs - see the Variables section.

Show Advanced Options:
Additional HTTP Headers: Any headers set here will be applied to all REST Methods for this service unless overridden in the REST Method.
Authentication: (See Authentication section)
Navigate to its folder (this happens automatically when the REST Service is created) and add REST Methods to it.

Creating a REST Method

The Rest Service folder is going to live in the folder where it was created. Inside the REST Service folder, click 'Add Method to Service'. Any URL defined here will be appended to the base URL defined in the REST Service. A base URL of "http://example.com/api/" might be paired with a relative URL of "fetch/users" to hit example.com/api/fetch/users, for example.

Configure the HTTP method and content type here.

The request body can be created from several different sources:

• Get String from Flow
• Get Binary Data from Flow: Sends the raw bytes instead of a string
• Serialize from Data Type: Choose a data type that'll be serialized to JSON or XML to create the request body
• Specify Below: Enter the request body here. This may include the variables here - see the Variables section.

There are several ways to handle the response returned from this request:

• Raw Value: Returns the entire response string
• Select Data Type: Choose a data type. The response string (JSON or XML) will be deserialized into the chosen type.
• Binary: Returns the raw bytes of the response
• None

Show Advanced Options:
Here, set the Accept header, custom headers, and 'Expect: 100-continue', among other options.

• Override Base URL: Ignore the base URL from the REST Service and instead get the base URL from the flow, the selected OAuth token, or a static string. (The relative URL will still be appended to this new base URL.)
• Override Authentication: Ignore the auth config on the REST Service and use these settings instead - see the Authentication section.

Variables

Variables can be defined as part of the URL in a REST Service or REST Method, as well as in the request body. These variables will appear as inputs to the REST Method flow step, and those input values will automatically be inserted in the appropriate locations when the step runs.

To include a variable in a URL or request body, put the variable name inside curly braces, with no spaces, like this: {myNewInput}

A complete example of a URL using a variable: https://example.com/api/fetch/{requestId}/accounts

Note that variable definition won't interfere with JSON in the request body, because the variable name must appear with no spaces or other special characters. For example, this request body defines 2 variables (company name and count) and includes them inside the JSON: { "name":"{companyName}", "count": {count} }

Authentication options

These appear on the REST Service and can also be overridden on each REST Method.

Basic Authentication:

• Pre-Authenticate Request: Includes credentials in the request header
• Use Static Credentials: Choose user and password here, rather than in the flow
• Windows auth: Uses windows credentials 

Important

The user account that this will use is the account running Service Host Manager and not the user account executing the step. This is the account next to SHM in the windows services dialogue under "Logon As"

OAuth:

From the Authentication settings, toggling Use OAuth Settings triggers the appearance of the OAuth panel below. 

The OAuth panel provides users with the following three options for OAuth : 

• Use Custom Tag in Auth Header (OAuth is Default): Allows the user to input a custom OAuth header tag; used in the event that the calling system is looking for 

• Use Static OAuth Token: Provides the user a drop-down menu that allows the user to select a pre-made OAuth Token. Without this enabled, the Token will be available as the Input. 

• Direct OAuth1 Signed Request: : Use OAuth1 to send a direct request signed with a private certificate. Provides the Consumer Key, Initial Token Data, PFX Filename, and PFX Password Input boxes; note, Consumer Key and PFX Filename are required for this option. 

Defining Headers in REST Service Using Advanced Options

To help with such errors as Proxy Authentication Errors, provide additional information, or if additional Authentication that cannot be fulfilled by the Authentication settings is required, users may add Custom Headers to their REST Service to pass in that information.

To do so:

1. Under System > Integrations > External Services
2. Right-click the desired REST Service and select Edit Service.
3. From the Edit Service window, under Service Definition, check the Show Advanced Options box. Under Service Definition [Advanced] > Additional HTTP Headers, click Add New. 
4. From the Add Additional HTTP Headers window, provide the Header Key and the Flow Step Variable Name, then click OK.
   Note on Additional Header Settings 

   The Header Key represents the name of the Header being passed into the call.
   
   The Flow Step Variable Name represents the Data Name that will be used as the step's input in the Flow Designer. 

   

   Further on Additional Header Settings 

   To find any Headers that may be required for the Integration via Flow, utilize API testing software such as Postman, and create a call using the Integration URL for the Service.
   
   Upon pasting in the URL, the Headers tab will populate with any Headers related to the Service. 

   
   

5. After all desired edits have been made, click OK.