User Guide > Process Steps and Components > Invoker Step > REST API Invoker 1.x
Was this helpful?
REST API Invoker 1.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.
Rest API Invoker Properties
Property Name
Default Value
Description
Protocol
HTTP
Select the secure and unsecure communication over SSL. Protocols supported are:
• HTTP
• HTTPS
• HTTPS (Debug)
HTTPS (Debug) allows SSL communication without a valid certificate.
URL
 
Main endpoint used by current REST session.
Space characters are automatically URL-encoded to "%20".
Send Source Via
BODY
Determines whether the Source DJMessage is sent in the HTTP body or appended to the URL and any specified URL query string (as a URL-encoded string).
Multiple URL parameters may be set and encoded 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
Content Type
text/xml; charset=UTF-8
Content-Type header in the HTTP request. The options available are:
• text/xml; charset=UTF-8
• text/xml; charset=ISO-8859-1
• application/x-www-form-urlencoded
HTTP Username
 
Username when Basic, Digest, or NTLM authentication schemes are required.
HTTP Password
 
The password to authenticate the above username.
Domain (NTLM Only)
 
Domain when Windows NTLM authentication scheme is required.
Proxy Server
 
Host name or IP address of a proxy server.
Proxy Port
 
Port on which the proxy server is listening.
Proxy Username
 
Username for proxy server where required. If NTLM authentication scheme is required, then the Domain (NTLM Only) option must also be set.
Proxy Password
 
The password to authenticate the above username.
Truststore File
 
Truststore file
Truststore Pswd
 
The password to access the trustore file
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 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
Parameter
Description
Execute
Source Message
Body of HTTP request.
Target Message
Body of HTTP request.
Supported Action Properties
Action
Property
Description
Execute
HTTP Method
The HTTP Method to be executed:
• POST (default)
• GET
• HEAD
• TRACE
• OPTIONS
• PUT
• DELETE
Note:  When using the POST method, the source message body is used as the body of the HTTP request. When using the PUT method, the source message body is assumed to be the URL of a file on the file system to use as the body of the request.
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. 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.
Example using Send Source Via == URL
URL: http://www.google.com/
Send Source Via: URL
URL Query String: ?var=
Source Message Text: "<test>Documents and Settings</test>"
Example using Send Source Via == BODY
URL: http://www.google.com
Send Source Via: BODY
URL Query String: ?var=%3Ctest%3EDocuments%20and%20Settings%3C%2Ftest%3E"
Resulting URL String in both Examples = "http://www.google.com/?var=%3Ctest%3EDocuments%20and%20Settings%3C%2Ftest%3E"
This option is ignored when one or more parameters are set with the Source Message Properties (see Additional Notes).
Execute
SOAP Action
Sets the SOAPAction header in the HTTP request, when required.
This value is only required when connecting to strongly typed web services.
Execute
Connect Retry Count
Determines the number of retry attempts made when an exception occurs. There is a one second delay between retry attempts. If the value is negative, the retry attempt default is zero.
Note:  If the method to be executed is GET, HEAD, TRACE, or OPTIONS, then multiple retry attempts are made regardless of exception. However, if the method to be executed is POST, PUT, or DELETE, multiple retry attempts are only made when the following exceptions occur:
• NoHttpResponseException
• ConnectTimeoutException
• UnknownHostException
• ProtocolException
• Connection is dropped before the request is fully sent to the server
Default is five retry attempts.
Execute
Connect Timeout (secs)
Determines the number of seconds to wait for a response once a socket connection is made.
If the value is set to <= 0 seconds, then time-out defaults to 30 seconds.
Note:  If a socket connection cannot be established or is dropped, then this value has no effect.
Default is 30.
Execute
Log HTTP Headers
When set to TRUE, all HTTP request and response headers are written to process log file.
Default is TRUE.
Execute
Write Response File
Click Browse and specify the file path. The response is written directly to the file, and not to the target message body.
When no file path is specified, response text is placed in 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.
Error Conditions
The REST API Invoker has the following error conditions.
Error Code
Description
50
Displayed for all run-time errors.
HTTP Status Code
Error Code = HTTP Status Code for all Status Codes >= 400
Error Code = 0 for all other Status Codes (including 200 OK), as Status Codes below 400 may be expected and/or desirable for certain requests.
Note:  For more details, see the HTTP 1.1 specification.
Limitations
The REST API Invoker has the following limitations:
• Kerberos authentication schemes are not currently supported.
• Multipart POST and MIME attachments are not currently supported.
Use Case - Managing Multiple URL Parameters
This component automatically scans for source message property names which begin with "P." or deprecated "_". If any exist, these properties are converted and encoded as URL parameters without the "P.". If Send Source Via == URL, then the source message body is ignored. If any URL Query Strings are present within the step, they are also ignored.
Example:
SourceMessage.Properties("P.var") = "<test>Documents and Settings</test>"
SourceMessage.Properties("P.var2") = "&&&&"
SourceMessage.Properties("P.var3") = "<<>>"
URL: http://www.google.com/
Resulting URL String = "http://www.google.com/?var=%3Ctest%3EDocuments%20and%20Settings%3C%2Ftest%3E&var2=%26%26%26%26&var3=%3C%3C%3E%3E"
Additional Notes
• Managing Session Cookies - This component automatically manages a single session cookie across invoker steps within a single invoker session.
In some cases it may be necessary to force a cookie value or to share a cookie across multiple invoker sessions or even subprocesses. Once a session is established, the cookie value can be retrieved using TargetMessage.Properties("Cookie"). This value can then be used to manually set or override the cookie for any invoker step using SourceMessage.Properties("Cookie"), regardless of the parent session of the step.
• Managing HTTP Headers - This component automatically scans for Source message Property Names which begin with "H.". If any exist, these properties create or override existing HTTP request headers.
SourceMessage.Properties("H.Content-Type") = "text/plain"
SourceMessage.Properties("H.CustomHeader") = "Some Value"
This code adds the following to the header:
Content-Type: text/plain
CustomHeader: Some Value
Last modified date: 10/22/2024