REST

You can use the REST plugin with any RESTful services you want to add to InsightConnect, or with the REST APIs of existing InsightConnect plugins. The REST plugin allows you to integrate services that aren’t yet available as InsightConnect plugins or customize actions that our plugins don’t currently support. Learn more about RESTful services at https://restfulapi.net/.

InsightConnect supports the GET, POST, PUT, PATCH, and DELETE HTTP methods with the REST plugin.

While the REST plugin is useful for addressing plugin needs that InsightConnect doesn’t yet support, we don’t recommend using the REST plugin for services that use OAuth authentication and authorization. OAuth processes require multiple authentication tokens and would need multiple REST plugins to appropriately connect the API service to InsightConnect.

Collect REST Plugin Configuration Information

Every API will have different requirements, but you will always need the API request client URL (cURL) to configure the REST plugin. The API service documentation will help you understand what methods the API supports, what JSON output the API provides, and any required configuration details you will need to integrate the service with InsightConnect.

API documentation is sometimes referred to as developer documentation. Visit the service’s website or support portals for more information.

Configure a REST Plugin Connection

To configure a REST plugin connection, add a new connection from the Connections tab of “Reusable Elements” page or during plugin configuration. Next, configure the connection parameters to the following values:

Passing Credentials as Headers

If you need to pass any type of credential or API key for authorization, be aware that the header values are not currently encrypted.

Connection Parameters

Acceptable Values

Basic Auth Credentials

Any username or password required for the API service you want to use, as strings

Base URL (required)

The API’s base URL up to and including the last required forward slash (before resource-specific paths), as a string.

Headers

Any API headers in JSON, including API keys, that you need for the action. The plugin will use these by default unless overwritten by any action-specific headers you specify

SSL Verify (required)

Boolean values: true if you want to verify SSL certificates, false if you don’t

Configure REST Plugin Actions

When adding a REST plugin action step to a workflow, you need to select or configure a connection, then configure step input fields for the action.

Every action corresponds to an HTTP method. Acceptable values for each input variable option are as follows:

Input Variable

Acceptable Values

Actions Using the Input Variable

Route (required)

The path to the resource without the base URL included, as a string.

GET, PUT, POST, DELETE, PATCH

Headers

Any API headers in JSON, including API keys, that you need for the action. Headers added in the step input will override default headers in the REST plugin connection.

You can leave this blank if you know the connection you’re using for the action is correctly configured for the HTTP method.

GET, PUT, POST, DELETE, PATCH

Body

Payload to submit to the server when making the REST call

PUT, POST, DELETE, PATCH

Sample REST Configuration

To show you what correctly formatted Base URL-route pairs look like, we’ll use the Star Wars API from https://swapi.co/documentation as an example.

The full path to the object containing data on Luke Skywalker is found at the URL http https://swapi.co/api/people/1. The base URL is described in the Star Wars API documentation as https://swapi.co/api/, so we know that the route should be anything in the full URL following that. The route for plugin configuration is people/1.

For further help, refer to the following sample screenshots.

Sample Connection Configuration for Star Wars API

Sample Plugin Input for Retrieving Luke Skywalker Entity

Test REST Configurations with Postman

You can use the Postman client to test your configuration values before activating your workflow. This is especially useful for APIs that require authorization or authentication.

Download the Postman app at https://www.getpostman.com/products. The free Postman plan is sufficient to test APIs with.

To test the REST plugin with the API you chose:

  1. In Postman, select the HTTP method for your REST plugin action in the dropdown to the left of the “Enter request URL” field.
  2. Copy the full cURL for the API request (base URL + route) and paste it into the “Enter request URL” field.
  3. If your API requires an API key, enter or paste in the name of the key into one of the open cells under the “Key” column of the “Params” tab. Then paste in the key value, or token, into the corresponding “Value” column cell. The API key name should match what you entered into InsightConnect as an API header.
  4. Click the blue Send button to send the request.
  5. Check the output in Postman. If you see something unexpected or receive an error message, visit your API’s documentation for troubleshooting help.

If you test your base URL and route and receive unexpected output in Postman, your API might require a final forward slash at the end of your route. In the example above, SWAPI does not require a final forward slash for people/1, but some APIs will not correctly send data without it.