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
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.
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.
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
Every action corresponds to an HTTP method. Acceptable values for each input variable option are as follows:
Actions Using the Input Variable
The path to the resource without the base URL included, as a string.
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.
Payload to submit to the server when making the REST call
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
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:
- In Postman, select the HTTP method for your REST plugin action in the dropdown to the left of the “Enter request URL” field.
- Copy the full cURL for the API request (base URL + route) and paste it into the “Enter request URL” field.
- 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.
- Click the blue Send button to send the request.
- 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.