Configuration

Channel

The first step when configuring the RestApiClient is to create a connection to a REST endpoint. This is represented by a channel. Channels have the following configuration:

Figure 3: Channel configuration

• Enable data collection: Enables data collection for this channel. If set to false, no requests on this channel will be executed.
• Connection: This section contains options related to the HTTP/HTTPS connection.
  • Protocol: Select between unsecure HTTP protocol or secure HTTPS protocol.
  • Host: Hostname or IP address of the target REST server without http:// or https://.
  • Port: TCP port where the target REST server will be listening. By default, HTTP uses port 80 and HTTPS uses port 443.
  • Options: This section contains additional options that are used when the protocol is HTTPS.
    • Reject untrusted certificates: When set to true, connections to the target HTTPS server will be silently dropped if the server supplies a certificate that is not signed by a trusted certificate authority. This can occur when using self-signed certificates. In this case, this option must be set to false.

• Timing: This section contains options related to timeouts and retries that affect all the requests in the channel.
  • Request timeout: Specifies how much time can pass after a request is sent to the server before it times out and is retried (in milliseconds). The default value it 10000 milliseconds.
  • Retries: Selects how many times a request will be retried before being aborted. The default value is 3 retries, which means that the request will be sent 4 times to the server (initial request plus 3 retries).
  • Transmission delay: Specifies the delay between one request and the next one on this channel (in milliseconds). The minimum value is 0, which means that the next request will be sent out as soon as possible after the current one finishes.

Request

A Request represents the REST request that is sent to the server. Requests have the following options:Figure 4: Request configuration

• Enable data collection: Enables or disables this request. If disabled, the request will never be sent to the server and any tags with this request as their source will remain with a BAD-UNIN-ITIALIZED quality.
• Method: Selects between the different HTTP REST methods. Some methods (such as GET) do not have a body (and as such, the body section is hidden), while others such as POST or PUT require a body.
• Rate: Sets the rate at which the request will be executed. This value only guarantees that the request will execute after this rate has passed. However, it may also be delayed if the transmission delay is too high, or if there are multiple slow requests on this channel.
• Parameters: List of parameters that will be available to all scripts in this request. More information about parameters can be found at $.parameter.
• Path: This section is used to obtain the path of the REST request. It can be one of two types:
  • Plain text: The path is created using a static string. This is the simplest way of creating the request path. However, paths that require dynamic values (such as a date, or values that depend on tags) cannot be created this way.
  • Custom script: Creates a path by executing a custom JavaScript script. This confers greater flexibility compared to plain text, since using this method means that the path can be created dynamically based on parameters. The path can be set by assigning the desired value to the $.output variable. More information can be found in the $.output section.
• Headers: This section is used to define which headers are sent with the request. More information about the headers can be found in the headers section.
• Body: This section only appears when the request needs a body (such as a POST, PUT, and PATCH requests) and is used to generate the body of the request. More information can be found in the body section.
• Response format: Establishes the expected response format.
  • Encoding: Determines the encoding of the response. Valid values are UTF8, Binary, Base64, and Hexadecimal.
  • Serialization: Determines the serialization of the incoming response. Valid values are Binary, Text, JSON and XML.
• Response parser: Determines how the response is parsed into a N3uron compatible format, which is then saved into tags.
  • Type: Selects the type of serializer used to parse the body. Currently, only Custom serializers are supported.
  • Script: User defined JavaScript code that will be used to parse the body of the response. The response received from the REST API server can be found in the $.input property (containing response body, response status code, and header). More information about scripts can be found in the user defined scripts section.

Headers

When executing a Request, headers are sent along with the request. Each request has a number of headers that are set automatically by the module and a variable number of custom headers created by the user. The below screenshot shows the configuration options for these headers & two custom headers.

Figure 5: Request header configuration

• Fixed headers: These headers are set automatically by the module. However, a custom header with the same name as these headers can be created to override this value.
• Accept-Encoding: Configures the Accept-Encoding header for the request, which is used to indicate which encoding the client can support to the server. Valid values are Gzip, Deflate, and None.
• Authorization: Configures the Authorization header for the request, which some servers use to determine whether the client is authorized to execute the REST request. The authorization header can be one of three types:
  • None: The authorization header is not added automatically. However, it can still be added as a custom header if custom authorization is desired.
  • Basic: Employs HTTP basic authentication using a username and password.
  • Bearer: Uses a static bearer token to authenticate with the server
• Custom headers: These headers are created by users and can either be used to override a fixed header (for example, if the server uses a custom authorization method) or to add headers that the REST server requires for servicing a request. The above figure displays two custom headers of the Accept and Content-Type.
  • Type: Custom headers can be created in two ways, either by using a static text, or by executing code to dynamically create the header. These correspond respectively to the raw text and custom script options.
  • Value: Sets the value of the custom header to the specified string. This option is only available for raw text types.
  • Script: The Script that will be used to dynamically generate the custom header. The header is set by assigning it to the script’s $.output property. More information can be found in $.output and information surrounding custom scripts can be found in user defined scripts. This option is only available for custom script types.

Body

This section is used to create the body that is sent with the request. These options will only appear when the REST method is either POST, PUT, or PATCH. The configuration used to create a body is as follows:

Figure 6: Request body configuration

• Body format: This section determines the format and encoding of the body.
  • Serialization: Determines how the body is serialized before being sent to the destination. Valid options are Binary, Text, JSON, and XML.
  • Encoding: Sets the encoding of the body after it is serialized. Valid options are UTF8, Binary, Base64, and Hexadecimal.
• Body serializer: Determines how the body of the request will be created.
  • Type: Selects the type of serializer used to create the body. Currently, only Custom serializers are supported.
  • Script: User defined JavaScript code that will be used to generate the body. The output of the script must be set in the $.output field. More information can be found in the $.output section and information about scripts can be found at user defined scripts.

Tag Configuration

RestApiClient can be used as a source module and as such, can generate tag events from REST requests. In order for these tag events to be valid, tags with the RestApiClient as their source must be created. See below screenshot for example configuration:Figure 7: Tag source configuration

• Enabled: When disabled, tags won’t be updated with the values received from the device. Instead, they will essentially act as memory tags. When set to enabled, the tag value will be continuously updated with the values received from the field device, or in this case, the REST server. The default value is set to disabled.
• Module type: Defines the driver type used to retrieve values from the field. In this example, RestApiClient must be selected from the drop-down menu. If RestApiClient does not appear in the drop-down menu, this means that this driver has not been installed on this machine yet and must be installed.
• Module name: Selects which instance of the RestApiClient module will provide the data for this tag.
• Config:
  • Enabled: Enables data collection for this tag. If disabled, no events can occur in this tag.
  • Request: Selects which request will provide data to this tag. The request must already exist in the selected RestApiClient instance. The format for this property is Channel/Request.
  • Alias: The alias can be used to associate this N3uron tag with the data retrieved from the REST server. This property can be left blank, which means that the full tag path must be used to assign the values received from the REST server. If a tag alias is used, tags can be referred to in the request parser using this alias, instead of the full tag path.