The REST Connection Form

Create a Connection with REST in Hero Platform_

1. Open Hero Platform_.
2. Open Integration from the navigation menu and select Connections.
   
3. Click Create New Connection.
   
   

4. Give the Connection a name and select REST from the drop-down list for Connection type.
   

   The Rest connector and the Rest Endpoint connector are separate Connection types with different purposes.
   

   • Rest Connection

     • Hero Platform_ is the active party that calls a REST API for requesting or sending data.

     • A REST API is required (e.g. GET https://yourdomain/api/v1/users) that can be called by Hero Platform_.

     • In the server-client terminology, Hero Platform_ is the client and the other application is the server.

   • Rest Endpoint Connection (Not used in this example)

     • Hero Platform_ is a passive party that waits for REST API calls.

     • A client service is required that calls Hero Platform_'s API for sending or retrieving data.

     • In server-client terminology, Hero Platform_ is the server and another application is the client.

   The ability for multiple REST Connections and Rest Endpoint Connections on the same Hero Platform_ instance is supported.

   Changing credentials on the REST Connection form has unpredictable effects on related Flows that are currently being executed. Make sure Flows using the REST Connection are stopped before making changes.

5. The REST Connection details screen is displayed with fields that need to be configured.
   

   • Select the authentication type from the drop-down list.
     

     REST APIs state what authentication is required for using them in their documentation. It is possible that a REST API offers multiple authentication options. These authentication types are IT standards. 

     If any type, other than "No authentication", is selected, Hero Platform_ manages the authentication and sends the required fields for authorization. The usernames, passwords, secrets, and ID's are provided by the REST API's owner (either by sending them individually or via their website).

     Some REST APIs require another way of authorization or sending authorization fields. (E.g. Send a token, registration number as a header value, cookie value, etc). In this case, select No authentication. This type of authorization can be added manually in different field on the form.

     • Basic authentication
       • Enter a username/password.
     • OAuth1.0a (Twitter only)
       • Enter a customer key/secret.
     • OAuth2 (Client Credentials Flow)
       • Enter a client ID, secret, and the token URI.
       • Hero Platform_ manages obtaining the authentication token with the required HTTP requests.
     • OAuth2 (Authentication Code Flow)
       • Enter a client ID, secret, auth URI, token URI, and scope.
       • Test connection functionality is only supported if the login happened recently. If the access token expires, an error is displayed.
       • Hero Platform_ manages obtaining the authentication token with the required HTTP requests.

     • No authentication

       • Hero Platform_ won't execute any additional authentication logic

   • Enter the request base URL

     At a minimum, the base URL must contain the:

     • protocol: https or http (HTTPS highly recommended)
     • host 
     • port number (if required)

     The base URL may also contain path segments.

     The base URL may end with a slash character ( / ). If the slash character is not added, it will be automatically added by Hero Platform_.
     
     Example:

     An API example with the full URL for the issue endpoint is: https://domain.com/rest/api/latest/issue 

     In this example, the base URL can be https://domain.com/rest/api/latest/ and in the Input and Lookup, the endpoint field must contain the rest of the URL. The point is that the concatenation of the base URL and the endpoint field should be the full URL of the desired resource.
     
     We could use these base URL's and endpoints:

     • https://domain.com/rest/api/latest and the endpoint will be issue or /issue
     • https://domain.com/rest/api/  and the endpoint will be latest/issue or /latest/issue
     • https://domain.com/rest/api  and the endpoint will be latest/issue or /latest/issue
     • https://domain.com/rest/  and the endpoint will be api/latest/issue or /api/latest/issue
     • https://domain.com/rest  and the endpoint will be api/latest/issue or /api/latest/issue
     • https://domain.com/ and the endpoint will be rest/api/latest/issue or /rest/api/latest/issue
       
We recommend using the longest possible base URL that fits for each endpoint.

     If the IP for the Base URL in the REST Connection is in the following ranges it will be restricted/error:

     • 10.0.0.0/8
     • 169.254.0.0/16
     • 172.16.0.0/12
     • 192.168.0.0/16

     If a the IP of the URL resides in one of these ranges, it can be overridden by the following commands from the customer’s Hero Platform_ sys admin:

     • -Dsecurity.restricted-ip-ranges.0=<ip>/<range>
     • -Dfeatures.restrict-ip-ranges=off

   • Enter request headers and/or cookie parameters if the target API requires providing extra headers or meta data. (Optional)

     These parameters are added to all Input, Output, and Lookup requests. Input, Output and Lookup parameters override the connector's parameters (if the same parameter is set on both forms). A selected authentication type can also add header parameters in the background which takes precedence.

     Some REST APIs require setting a header or cookie value for authorization of the HTTP requests (E.g. Send a token, registration number as a header value, cookie value, etc). The authorization fields can be added manually with these controls.

     Header and cookie parameters are stored encrypted for security as they often contain sensitive data.

     Some REST API's require sending meta information such as the preferred: locale, language, encoding, or response format.

   • Enter the connection timeout value.
   • Enter the socket timeout value.

   • Check the box to enable automatic retries. (Optional, but recommended)
     

     Enabling automatic retries instructs Hero Platform_ to resend the HTTP request after a short delay (max 3 tries) if the server is not available or doesn't respond. It's recommended to account for server restarts or occasional network glitches.

     
     

   • Leave the follow redirects box unchecked. This option is not recommend other than special circumstances. 
     

     Advanced setting for only edge cases!

     The server can send a redirect response to a request. This is needed when an endpoint is moved or the request is sent via HTTP instead of HTTPS. It's highly recommended to update the Connection / Input / Output / Lookup to use correct URL and/or the correct protocol instead of using this option.

   
   
   
6. Click Test connection. A confirmation message is displayed if the connection has been established.
   

   To test a connection, Automation Hero recommends selecting an HTTP method and endpoint that (if possible):

   • doesn’t require any parameters.

   • results a non-html response.

   • uses the same authentication method as the connection.

   If the test method or test endpoint is not configured correctly, the test might produce a false positive or false negative result.
   
   If there is not an endpoint to use for testing, the connector can still be used in the Flow.

   WARNING: Testing the connection sends a real HTTP request. Avoid the usage of endpoints that modify or trigger actions.

   
   

7. Click OK to finish saving the Connection in Hero Platform_.