REST Connector

Version 20.0.7681


REST Connector


REST Connectors support building dynamic REST requests to consume RESTful API web services.

Overview

REST connectors expose a simple interface to build the headers, authorization, body, and HTTP method for a REST request. The request body can be set statically within the connector configuration or dynamically generated based on the files processed by the connector.

Connector Settings

Settings Tab

Configuration

Settings related to the core configuration of the connector.

  • Connector Id The static name of the connector. All connector-specific files are held in a folder by the same name within the Data Directory.
  • Connector Description An optional field to provide free-form description of the connector and its role in the flow.
  • Method & URL The HTTP method and target HTTP URL for the REST request.

Authentication

Settings related to authenticating with the REST service.

  • Authorization Type The type of authentication to use with the REST service. Please see the Authenticating section for more details.

The Header section supports adding an arbitrary list of HTTP headers to include in the outgoing REST request. Headers are specified as name-value pairs. This section can be used to specify the Content-Type of the message body when the Body Type is set to Raw.

Body

Settings related to generating the body of the REST request. Not applicable when the HTTP method is set to ‘GET’.

  • Body Type None - No body will be supplied with the REST request.

    form-data - The body is supplied as a set of name-value pairs (fields). If the field is set to static, then both the Name and the Value are specified in the UI. For dynamic fields, the Name is specified in the UI and the Value is dynamically read from the input file processed by the connector. For more information, see the Dynamic Form Data section.

    x-www-urlencoded - The body is configured in the same way as form-data, however the name-value pairs are encoded as a URL query string instead of multipart form data.

    raw - The body is set to the contents of the input file processed by the connector. The content-type of the body can set via the associated dropdown menu, or specified as a custom header in the Header section.

SSL Server Authentication

Settings related to verifying the SSL server’s identity.

  • SSL Server Certificate The public key certificate used to verify the identity of an SSL/TLS server. This setting can be left blank, to allow the underlying OS/JVM to perform certificate validation, or it can be set to ‘Any Certificate’ to unconditionally trust the target server’s identity.

Automation Tab

Automation Settings

Settings related to the automatic processing of files by the connector.

  • Send Whether files arriving at the connector will automatically trigger a REST API call.
  • Retry Interval The amount of time before a failed REST request is retried.
  • Retry Maximum Attempts The maximum number of times a failed REST request will be retried.
  • Receive Whether the connector should automatically send static REST requests according to a specified interval. No dynamic values will be included in the request body.
  • Receive Interval The interval between automatic static requests.
  • Minutes The number of minutes to wait before sending a request. Only applicable when Receive Interval is set to Minute.
  • Minutes Past the Hour The minutes offset for an hourly schedule. Only applicable when Receive Interval is set to Hourly. For example, if this value is set to 5, the automation service will send requests at 1:05, 2:05, 3:05, etc.
  • Time The time within a given day that the request should be sent. Only applicable when Receive Interval is set to Daily, or Weekly, or Monthly.
  • Day The day on which the request should be sent. Only applicable when Receive Interval is set to Weekly or Monthly.
  • Cron Expression An arbitrary string representing a cron expression that determines when the request should be sent. Only applicable when Receive Interval is set to Advanced.

Advanced Tab

Local Folders

Settings that determine where files will be read from and processed to.

  • Input Folder (Send) Files placed here will be converted into a request by the connector. If Send Automation is enabled, the connector will automatically poll this location for files to trigger a request.
  • Output Folder (Receive) Files that are downloaded by the connector will be placed here. If the connector is connected to another connector in the flow, files will not remain here and will instead be passed along to the Input/Send folder for the connected connector.
  • Processed Folder (Sent) The connector will place a copy of processed files here if Save to Sent Folder is enabled. This copy of the file will not be passed along to the next connector in the flow.

SSL Client Authentication

Settings related to client authentication when two-way SSL authentication is required.

  • Private Certificate The private certificate presented during SSL client authentication.
  • Certificate Password The password required to access the SSL client certificate.

Other Settings

Settings not included in the previous categories.

  • HTTP Version Whether to use HTTP 1.0, 1.1, or 2.0 when connecting to the REST service.
  • Timeout The duration in seconds to wait for a response from the REST server before throwing a Timeout error.
  • Use Chunked Encoding Whether to use HTTP Chunked Transfer Encoding when sending requests. This allows the application to send portions (chunks) of the message sequentially to avoid overloading the connection.
  • Chunk Size The size, in bytes, of each chunk when Use Chunked Encoding is enabled.
  • Log Level The level of detail included in logs generated for the connector.
  • Log Messages Whether logs from sent files will include a copy of the file itself.
  • Save to Sent Folder Whether files sent by the connector should be copied to the Sent folder for the connector.
  • SSL Enabled Protocols The list of SSL/TLS protocols supported when establishing outgoing connections. It is strongly recommended to only use TLS protocols. Some obsolete operating systems do not support TLS 1.2.

Establishing a Connection

A valid target URL is required to establish a connection to any REST service. The service URL may support various HTTP methods, and Method should be configured based on particular web service action or data set to retrieve. Some services may also require authentication or a set of custom headers in order to consume the service.

If the target URL is an ‘https’ URL, the SSL Server Certificate should be set to the public key certificate identifying the server. This field can be set to ‘Any Certificate’ to implicitly trust the target endpoint.

Authenticating

The REST Connector supports username-password authentication in Basic (plaintext) or Digest (encrypted) formats. These credentials are supplied to the REST service as headers in the request.

The REST Connector also supports OAuth authentication, but the OAuth access token and refresh token must be acquired ahead-of-time. Use the REST service’s web portal or development console to find/generate the appropriate OAuth tokens. The connector then handles the process of automatically refreshing the token, so that once the OAuth configuration values are supplied the first time, the connector is continuously able to connect.

Finally, the REST Connector supports signing the outbound request according to the AWS Signature specifications required by Amazon. This option requires configuring credentials provided by Amazon: Access Key, Secret Key, etc.

Static Requests

REST requests that have entirely static content (e.g. requests that use the HTTP GET method) do not require an Input file, since the request content is configured entirely within the connector UI. Simply add any necessary name-value pairs as custom headers in the Header section or form data in the Body section.

Static requests can be automatically sent according to a schedule if Receive Automation is enabled. The response to each request will be stored in the Output/Receive Folder or passed along to the next connector in the flow.

If Send Automation is enabled, files arriving at the Input/Send Folder of the connector will also trigger a static request. The content of the input file is ignored, and the request is sent according to the configuration in the UI.

Dynamic Requests

REST requests can be dynamically populated with data from files that arrive in the Input/Send Folder of the connector.

Raw Input Data

If the Body Type of the request is set to ‘raw’, the content of input files will be sent as the body of the REST request.

The specific content-type of the data can be set via the content-type dropdown. It might be necessary to add a Content-Type header in the Header section if the desired content-type is not listed.

Dynamic Form Data

If the Body Type of the request is set to ‘form-data’ or ‘x-www-urlencoded’, then the connector will look for specific values from the input file to populate the request. For each Body field that is set to ‘Dynamic’, the connector will scan input files for an XML element that shares the same name as the field name, and that follows a particular XML structure:

<Items>
  <FormData>
    <FieldName></FieldName>
  </FormData>
</Items>

To fit this structure, it is strongly recommended to use an XML Map connector prior to the REST connector in the flow, as described below.

When an element that matches the field name and required XML structure is found, the value within this element is used as the value in the Body field. For example, if the Body has a dynamic field with the name ‘CustomerID’, and the input file had the following XML:

<Items>
  <FormData>
    <CustomerID>12354</CustomerID>
  </FormData>
</Items>

Then the REST connector would then set the value of the ‘CustomerID’ field to 12354.

Dynamic Templates with XML Map

The XML Map connector should be used in conjunction with the REST connector to easily build dynamic requests out of other XML data structures. The XML Map connector converts arbitrary custom XML structures into the XML structure that the REST connector expects.

First, configure the REST connector with the set of dynamic (and static) Body fields that should be present in the request. Then, connect an XML Map connector to the REST connector in the ArcESB flow and save the flow changes. This allows the XML Map connector to detect which fields the REST connector expects in incoming input files.

Then, inside the XML Map connector, the Destination File dropdown includes the REST request schema. Select this as the Destination, and set the Source File to any arbitrary custom XML structure. This will populate the XML Map designer view, and the data that should be included in the REST request can be dragged-and-dropped from the Source structure into the Destination structure. After the mapping is complete, the XML Map connector will automatically convert files that match the Source File into a valid REST request structure.

For more information on using the XML Map connector, please see the XML Map connector documentation