The REST Connection Form


Introduction

If you are new to this topic, please read: Create a REST Connection

Read a full example using the REST API tools in Hero_Flow: REST Connection Example - Finding Definitions for English Words

Create a Connection with REST in Hero_Flow

  1. Open Hero_Flow.
  2. Click Connections from the menu on the left.
  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_Flow 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_Flow.

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

    • Rest Endpoint Connection (Not used in this example)

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

      • A client service is required that calls Hero_Flow’s API for sending or retrieving data.

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

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

  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_Flow 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.
      • OAuth2 (Authentication Code Flow)
        • Enter a client ID, secret, auth URI, token URI, and scope.
      • No authentication

        • Hero Flow 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_Flow.

      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.
    • 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_Flow 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_Flow.