REST API Invoker 3.x
The REST API Invoker component implements the client side of HTTP protocol used as communication channel between many enterprise and distributed applications. It can be used to execute simple HTTP requests and to invoke REST and SOAP web services
In addition to the capabilities available in REST API Invoker 2.x, REST API Invoker 3.x supports the following additional features:
• Support for RESTClient tool that facilitates interactive testing of an HTTP resource. This reduces the need to use external tools such as SoapUI to test the HTTP resource.
• Support for OAuth2 authorization code grant type.
• Session-level options such as URL, Send Source Via, and Content Type are moved to the step-level options so that the same instance of the REST API Invoker can be used in multiple steps.
Supported Scenarios
The REST API Invoker 3.x supports the following scenarios:
• Non-secure connection to a server: In this case, there is no need to configure a truststore or keystore.
• Server uses a certificate that is either self-signed or signed by an unknown certificate authority (CA): In this case, you must download the self-signed certificate or the unknown CA to the local system and do one of the following:
– Install the self-signed certificate or unknown CA into the lib/security/cacerts file of the JRE. In this case, the REST API Invoker configuration is not required.
– Install the self-signed certificate or unknown CA into a custom truststore (a Java keystore file that will be used specifically to determine the trustworthiness of the server) and configure the REST API Invoker to use the custom truststore.
• Server requires that the client present a certificate that is self-signed or signed by a custom CA. In this case, the client must install the certificate or certificate chain into a local java keystore and configure the REST API Invoker to provide it to the server when requested (during initial SSL handshake).
REST API Invoker 3.x Properties
Property | Default Value | Description |
|---|---|---|
Protocol | HTTP | Supports secure and unsecure communication over SSL. Supported protocols are: • HTTP (default) • HTTPS • HTTPS (Debug) HTTPS requires the use of a trust store. HTTPS (Debug) allows establishment of a secure connection to a server which doesn't have a valid certificate (self-signed, signed by unrecognized certificate authority, etc.) |
Authentication | None | Supported server Authentication: • BASIC • DIGEST • NTLM • OAuth2 Bearer |
Message Encoding | UTF-8 | The text encoding to use in the body of the source and target DJMessage objects: UTF-8 or ISO-8859-1. |
Use Base64 Encoding | No | Indicates whether binary source messages (like DJMessage attachments) must be encoded in Base64 before being sent. |
HTTP Username | The user name when Basic, Digest, or NTLM authentication schemes are required. | |
HTTP Password | The password when Basic, Digest, or NTLM authentication schemes are required. | |
Domain | The domain when Windows NTLM authentication scheme is required. | |
Bearer Token | The Bearer Token when OAuth2 Bearer authentication scheme is required. | |
Proxy Server | The host name or IP address of the proxy server. | |
Proxy Port | The port on which the proxy server is listening. | |
Proxy Username | The user name for the proxy server, where required. If an NTLM authentication scheme is required, you must also set the Domain (NTLM Only) option. | |
Proxy Password | The password for the proxy server, where required. | |
Keystore File | The keystore file that the REST API Invoker must provide to the server during initial SSL handshake. This property appears only when the Protocol property is set to HTTPS. Note: The certificate or the certificate chain must be installed into a local java keystore. | |
Keystore Pswd | The keystore password for the keystore file. This property appears only when the Protocol property is set to HTTPS. | |
Truststore File | The full path to the trust store certificate. The truststore is a java keystore which is used by the client to match against the signing authorities of certificates presented by servers to which you are attempting to establish secure connections. This property appears only when the Protocol property is set to HTTPS. | |
Truststore Pswd | The password to access the specified trust store. This property appears only when the Protocol property is set to HTTPS. |
Supported Actions
Action | Description |
|---|---|
Execute | Executes the supported actions listed in Supported Action Properties. |
Disconnect | Closes an existing database connection and performs any clean up actions if required. |
Supported Action Parameters
Action | Property | Description |
Execute | SourceMessage | Body of HTTP request. If HTTP method is GET or HEAD, this may be treated as an optional parameter. |
Execute | TargetMessage | Contains the HTTP response information. |
Supported Action Properties
Action | Property | Description |
|---|---|---|
Execute | Design | Click within the field and then click  to open the Rest API Invoker 3 Configuration window.After configuring the values in this tool, save the configuration. |
Execute | HTTP Method | The HTTP method to be executed: • POST (default) • GET • HEAD • TRACE • OPTIONS • PUT • DELETE • PATCH Note: For more information, see the HTTP 1.1 specification. |
Execute | URL | The endpoint of the current REST session. |
Execute | URL Query String | Allows a query string or additional URL information to be appended to the URL. The URL is appended in the following manner: URL + URL Query String + URL-Encoded String. URL-Encoded String is taken from the Source Message when Send Source Via == URL. Any value used within this option is read literally and must already be URL-Encoded. |
Execute | Headers | HTTP request headers. Formats: key1:value1;key2:value20;key2:value21 ..... The following is a header example. Here, “Authorization” is the key and “Bearer...” is the value: Authorization:Bearer d7443b7f11508f3dedb37c9911e2e231d418a969b4703141eddc1468b367dd0a At run-time, the input message can define message properties start with 'H.' for header. |
Execute | Cookies | HTTP cookie. Formats: key1=value1;key2=value2 ..... The following is a cookie example. Here, “test_cookie” is the key and “cookie_value” is the value: test_cookie:cookie_value At run-time, the input message can define message properties 'Cookie'. |
Execute | Send Source Via | Specifies whether the source DJMessage is sent in the HTTP body or appended to the URL and any URL query string (as a URL-encoded string) that has been specified. The options are: • BODY • URL The default value is BODY |
Execute | Content Type | The content type for the header of an HTTP request. Provided types are: • text/xml (default) • text/html • text/plain • application/json • application/x-www-form-urlencoded • application/xml • multipart/form-data • application/atom+xml • application/octet-stream • application/svg+xml • application/xhtml+xml • wildcard Note: You can also type any other content type in this text box. |
Execute | SOAP Action | Sets the SOAPAction header in the HTTP request, when required. This value is required only when connecting to strongly typed web services. |
Execute | Connect Retry Count | The number of retry attempts to make when an exception occurs. If the value is negative, the retry attempt default is zero. The Connect Retry Delay property value is used between retry events. Note: If the method to be executed is GET, HEAD, TRACE, or OPTIONS, multiple retry attempts are made regardless of any exceptions. If the method to be executed is POST, PUT, or DELETE, multiple retry attempts are made only when the following exceptions occur: • NoHttpResponseException • ConnectTimeoutException • UnknownHostException • ProtocolException • Connection is dropped before the request is fully sent to the server Default is 5. |
Execute | Connect Retry Delay (ms) | The time (in milliseconds) to wait between retry attempts. The default value is 1000. |
Execute | Log HTTP Headers | When set to TRUE, all HTTP request and response headers are written to a process log file. Default is TRUE. |
Execute | Read Source File | The file that is to be upload. |
Execute | Read Source Folder | For multipart post requests, specify the folder location that contains the file that is to be uploaded. By default, all of the files in the specified folder are added to the request. To request specific files, you can add the following to a Script step before the invoker is called: requestMsg.properties("F.<filename>") = "<filepath>" You must add this line for each file you specify. See DJMessage Options for more information. |
Execute | Write Source File | Write the HTTP request to the specified file. If not provided, the content of the source DJMessage will not be copied to a file |
Execute | Write Response File | Write the HTTP response to the specified file. If not provided, the response is written to the target DJMessage. |
DJMessage Options
• Custom Headers - Any REST API Invoker 2 call can contain custom headers that are specific to the web service being accessed. To add a custom header, add the following script to the source DJMessage:
srcMsg.properties("H.<HeaderName>") = "<Header Value>"
For example, a specific call might require a header called Authorization that takes a token for its value. This call might look like the following:
srcMsg.properties("Authorization") = "09bf14tzrw426b71fx6adfad12"
• Multipart Post Options - When making multipart post requests, you must customize the following options for your request:
– Specify a File to Send: You can specify a request folder and file name. The <FileName> is relative to the folder that is specified and the name of the file, including the extension.
srcMsg.properties("F.<FileName>") = "<FilePath>"
– Specify the Content-Type of a File: By default, each file in a multipart post request uses the global content-type (the Content Type you set for the invoker). However, it is possible that some of the files you send will have a different content-type. To specify a different content-type for a specific file, use the syntax below. The file name should include the file extension.
srcMsg.properties("C.<FileName>" ) = "<content-type>"
– Specify the Name Field of the Content-Disposition Header for a File: Certain web services may require the name field of the content-disposition header to have a certain value in order to successfully upload a file. For example, a web service may expect a content-disposition header of the following form:
Content-Disposition: attachment; filename="accounts.csv"; name="spreadsheet"
By default, the name field is set to file for each file in the multipart post. If a file in a multipart post requires a specific name, you can specify the correct name using the following syntax:
srcMsg.properties("N.<FileName>") = "<content disp.name>"
Using Rest API Invoker 3.x Configuration Tool
The Rest API Invoker 3.x Configuration tool facilitates interactive testing of the target HTTP resource.
The following features are supported:
• Specifying the target URL
• Setting the following:
– Request method
– Request headers
– Cookies
– Request body
• Setting or configuring authentication
• SSL configuration, including specifying the keystore and truststore
• Viewing or collecting the following:
– Response headers
– Response cookies
– Response body
• Formatted viewing of specific response content types
– text/xml
– application/xml
– application/json
After configuring values in this tool, the new values are applied to the component’s options and the component responds by updating all the applicable option values before returning.
For more information about this tool, in the Rest API Invoker 3 Configuration window, click Help > RESTClient Kindle and read the documentation.
Errors
You may encounter errors when you run your process. The following table shows messages error codes and their descriptions.
Code | Name | Description | Possible Reason |
|---|---|---|---|
0 | OK | No error. Used for all informational messages. | - |
50 | UNSPECIFIED | An unexpected error occurred. Displayed for all run-time errors. | - |
4 | READ ERROR | A file, input stream, or web service response could not be read. | - |
27 | CLOSE ERROR | A file or input stream could not be closed. | - |
20 | BAD FILE TYPE | The specified directory or file does not exist. | - |
11 | RECORD TOO BIG | A file or input stream is too large to be read by the invoker (the maximum size is 2147483647 characters). | - |
34 | INVALID | An option is invalid. | The invoker was redirected to an invalid location. For example, no location header was specified. |
44 | NOT SUPPORTED | An option is not specified. | The invoker could not encode a binary attachment to base 64 due to a charset error. |
Last modified date: 02/01/2024