REST Endpoint Integration

With the REST endpoint integration, you can connect Cloudhouse Guardian (Guardian) to another service using API calls. Once you have configured the integration, you can set up GuardianActions to trigger API calls when certain events take place. For example, you might want to store login records in your own internal system. You can do that using this integration and action combination.

Note: This topic focuses on setting up the REST Endpoint integration. If you've already set up the integration and want to configure a REST Endpoint action, see Action: Send a Message to REST Endpoint.

Dependencies

To configure a REST endpoint integration, you need:

  • The API endpoint URL for your desired API call.

  • Authentication credentials with the API service provider, unless no authentication is required.

Add a REST Endpoint Integration

Integrating a REST Endpoint withGuardianestablishes a seamless connection to trigger API calls when certain events take place.

To add a REST endpoint integration, complete the following steps:

  1. In the Guardian web application, navigate to the Integrations tab (Control > Integrations) and click Add Integration. The Add Integration page is displayed.

  2. Select REST Endpoint from the list of available integrations. Here, you are required to complete the following options:

    Screenshot of the Guardian Add Integrations page with a highlight box around the REST Endpoint button.

    Option

    Description

    Name field

    		 The display name for the integration within Guardian. This name is how you will identify the integration among all others configured in your Guardian instance, so ensure it is descriptive.

    Endpoint URL field

    When making an API call, the endpoint is the point of communication with the service provider. This is where the data that makes up your call is sent. Enter the specific endpoint URL here.

    Authentication radio buttons

    The authentication method expected by the endpoint being called. Select from the following options:

    • 'No Auth' – No authentication is required by the endpoint.

    • 'Basic Auth' – Displays theUsername and Password fields, as described below.

    • 'Authorization Header' – Displays theAuthorization Header Value field, as described below.

    Tip: If you are unsure which authentication method to select, refer to the API documentation provided by the service you are calling.
    Username and Password fields

    Endpoints that use basic authentication requires a username and password when being called. Enter the username and password for your designated endpoint in these fields.

    Note: These fields are only displayed when 'Basic Auth' is selected as the Authentication method.
    Authorization Header Value field

    Endpoints that use authorization headers require only a single value to authorize an API call. These values are often encrypted keys that, when sent as part of an API call, authenticate the user. Enter your key or authorization value here.

    Note: This field is only displayed when 'Authorization Header' is selected as the Authentication method.
    Request Method radio buttons

    The type of request you want to make to this endpoint. Select from the following options:

    • 'GET' – Calls made by this integration are meant to retrieve information from the designated endpoint.

    • 'POST' – Calls made by this integration are meant to submit information to the designated endpoint.
    Body field

    During configuration, Guardian sends a test call to your designated endpoint. In this field, enter a JSON-formatted request body to use in this test call. Keep in mind that the parameters in the body depend on what's expected by the endpoint being called. Refer to the endpoint's documentation when compiling your request.

    Note: This request body is only used during the initial test call performed by Guardian. When configuring REST endpoint actions, you can define specific request bodies to send when your API calls are triggered.
    Bypass Certificate Validation (not recommended) checkbox When performing an API call, Guardian automatically validates the SSL certificate of that endpoint. If this validation fails, the call is not performed. However, you can choose to skip this step by selecting this checkbox. If selected, SSL certificate validation is bypassed. If not selected, validation is performed like normal.
    Custom Headers (one per line) field

    API headers provide additional information about the call being made that is not integral to the request body itself. Here, you can enter any additional headers to include in the calls made using this integration.

    Headers are formatted using key/value pairs, and you can include one pair per line in this field. So, your entry will look something like this:

    Copy 
    "key1" value1
    "key2" value2
    "key3" value3

  3. Once you have set the correct values for each of the options displayed, click Done to create the REST endpoint integration.

Once you click Done, Guardian automatically makes a call to the endpoint using details you've entered. Depending on the purpose of the endpoint you've configured, look for confirmation of the call where appropriate. For example, if you were to configure a Slack REST endpoint, you would see a test message in Slack that was sent using the details provided.

Troubleshooting

If the call to your endpoint fails, consider the following when troubleshooting:

  • Ensure that the authentication credentials you've entered are correct. Invalid credentials will lead to a failed API call.

  • Verify you have selected the proper request method. Selecting 'POST' when you are trying to get information from the endpoint will not work, nor will selecting 'GET' when sending information to the endpoint.

  • Format your request body using JSON, including parameters as they are defined by the API provider. Incorrectly formatted parameters will not be processed successfully when they reach the endpoint being called, which will result in a failed or incomplete API call.