User Guide > Process Steps and Components > Invoker Step > REST API Invoker 2.x
Was this helpful?
REST API Invoker 2.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 1.x, REST API Invoker 2.x supports the following additional features:
• NTLM v2 authentication
• Multipart post requests
• Binary attachments with and without base 64 encoding
In REST API Invoker 2.x, the response headers are available as properties of the target DJMessage, if specified.
Supported Scenarios
The REST API Invoker 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 2.x Properties
Property
Default Value
Description
Protocol
HTTP
Supports secure and unsecure communication over SSL. Protocols supported are
• HTTP
• HTTPS
• HTTPS (Debug)
HTTPS requires the use of a trust store.
HTTPS (Debug) allows SSL communication without the use of a valid certificate by trusting all certificates.
URL
 
The endpoint of the current REST API session. Include the port number if required. The format is <protocol>://<domain name>:<port number>/resource path. For example: http://www.mywebservice.com:80/Specific/API/URL
Make sure the URL is encoded properly before adding the value for this property. Contact the administrator of your Web service endpoint if you are not sure of the encoding that is required.
Send Source Via
BODY
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.
You can set and encode multiple URL parameters using source message properties (see Additional Notes).
Message Encoding
UTF-8
Text encoding to be used in the body of the source and target DJMessage objects. The available options are:
• UTF-8
• ISO-8859-1
Use Base64 Encoding
No
When sending a binary attachment, indicates whether the attachment must be encoded in base 64 before being sent.
Content Type
text/xml
The content type for the header of an HTTP request.
Supported types:
• text/xml
• 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
HTTP Username
 
The username when Basic, Digest, or NTLM authentication schemes are required.
HTTP Password
 
The password to authenticate the above username.
Domain (NTLM Only)
 
The domain when Windows NTLM 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 username 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 to authenticate the above username.
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 from the keystore location.
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.
SSL/TLS Version
Any
Determines the SSL context or the enabled protocol for SSL.
This option is displayed only when the Protocol is set to HTTPS or HTTPS (Debug).
The supported SSL and TLS protocols are:
• Any
• SSLv3
• TLSv1
• TLSv1.1
• TLSv1.2
If you select Any, the SSL/TLS protocol is decided by Apache http component and Java runtime.
The default value is Any.
Make sure that Java is installed to use these SSL and TLS version protocols.
Supported Actions
Action
Description
Execute
Executes the actions listed in Supported Action Properties.
Disconnect
Closes an existing database connection and performs any cleanup actions if required.
Supported Action Parameters
Action
Property
Description
Execute
SourceMessage
Body of the HTTP request.
Execute
TargetMessage
Body of the HTTP request.
Supported Action Properties
Action
Property
Description
Execute
HTTP Method
HTTP Method to be executed:
• POST (default)
• GET
• HEAD
• TRACE
• OPTIONS
• PUT
• DELETE
• PATCH
Note:  For more details, see the HTTP 1.1 specification.
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. The string will be URL encoded in the following MIME format:
application/x-www-form-urlencoded
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
Allows you to specify a file that you want to post.
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 Multipart Post Options - When making multipart post requests, you must customize the following options for your request: for more information.
Execute
Write Response File
If a file name is not specified, response text is placed in the target message body.
If the file name is specified, the response is written directly to the file instead of the target message body.
Use this option in the following situations:
• The response is known to be very large.
• The response may have invalid characters for the specified encoding scheme.
Execute
Write Response Folder
If a file path is not specified, response text is placed in the target message body.
If the file path is specified, a response is written directly to the file instead of the target message body.
Use this option in the following situations:
• The response is known to be very large.
• The response may have invalid characters for the specified encoding scheme.
DJMessage Options
• Custom Headers - Any REST API Invoker 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>"
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: 10/22/2024