RESTRequest node
Use the RESTRequest node to issue synchronous requests to external REST APIs.
- Developer
- Application Integration Suite
- Standard
- Advanced
- Express
- Scale
- Adapter
This topic contains the following sections:
Purpose
You can use a RESTRequest node in a message flow to issue synchronous requests to external REST APIs. The RESTRequest node uses an imported Swagger document in either JSON or YAML format, which you can import from the toolkit workspace, your file system, or from a URL.
If you have created a REST API from scratch in the IBM® Integration Toolkit, a Swagger document was created for you, which you can now import and use with the RESTRequest node. For more information about creating REST APIs, see Creating a REST API.
The RESTRequest node handles messages in the following message domains:
- DFDL
- XMLNSC
- JSON
- BLOB
- MIME
- XMLNS
- MRM
The RESTRequest node is contained in the REST drawer of the palette, and is represented in the IBM Integration Toolkit by the following icon:
Using the RESTRequest node in a message flow
The RESTRequest node can be used in a message flow to invoke a REST API. For information about how to use it, see Calling REST APIs by using the RESTRequest node.
Terminals and properties
The RESTRequest node terminals are described in the following table.
| Terminal | Description |
|---|---|
| In | The input terminal that accepts a message for processing by the node. |
| Failure | The output terminal to which the message is routed if a failure is detected during processing in the node. |
| Out | The output terminal to which the message is routed if it represents successful completion of the REST API request, and if further processing is required within this message flow. |
| Error | The output terminal to which messages that include an HTTP status code that is not in the range 200 through 299, including redirection codes (3xx) if you have not set the property Follow HTTP(s) redirection property, is routed. |
The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk on the panel if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the BAR file to deploy it).
The RESTRequest node Description properties are described in the following table.
| Property | M | C | Default | Description |
|---|---|---|---|---|
| Node name | No | No | The node type, RESTRequest | The name of the node. |
| Short description | No | No | A brief description of the node. | |
| Long description | No | No | Text that describes the purpose of the node in the message flow. |
The RESTRequest node Basic properties are described in the following table.
| Property | M | C | Default | Description | mqsiapplybaroverride command property |
|---|---|---|---|---|---|
| Definitions file | Yes | No | The name of a file containing the definitions for the REST API that you want to invoke. This file must be a valid Swagger 2.0 document, and can be in either JSON or YAML format. | ||
| Operation | Yes | No | The name of the operation in the REST API that you want to invoke. | ||
| Security identity | No | Yes | The name of the security identity object that
contains the user ID, password, and API key to be used by the integration
node to authenticate to the REST API. Use the mqsisetdbparms command to create
and configure the security identity object, and to set the user ID,
password, and API key to be accessed by the integration node. The
credentials can be specified in the security identity in any one of
the following combinations:
The default value for this property is an empty string, which signifies that the RESTRequest node will not attempt to authenticate to the REST API. For more information about REST API security identity support, see mqsisetdbparms command. |
securityIdentity | |
| Request timeout (sec) | Yes | Yes | 120 | The time in seconds that the node waits for a response from the REST API. The valid range is 1 through (231)-1. You cannot enter a value that represents an unlimited wait. The timeout might take up to one second longer than the specified value. | timeoutForServer |
| Base URL override | No | Yes | The base URL to use when making an HTTP request to the REST API. By default, the base URL from the REST API definitions file is used. | baseURL |
The RESTRequest node HTTP Settings properties are described in the following table.
| Property | M | C | Default | Description | mqsiapplybaroverride command property |
|---|---|---|---|---|---|
| HTTP(S) proxy location | No | Yes | The proxy server to which requests are sent.
This value must be in the form hostname:port. If the configured proxy server requires
authentication, the credentials must be set by using the mqsisetdbparms command with
the resource name |
httpProxyLocation | |
| Follow HTTP(S) redirection | No | No | Cleared | If you select the check box, redirections are followed. If you clear this check box, redirections are not followed. | |
| Enable HTTP/1.1 keep-alive | No | Yes | Selected | Use HTTP/1.1 Keep-Alive. | enableKeepAlive |
| Use compression | No | Yes | None | This property controls whether the content of
the HTTP request is compressed. You can choose a value from none, gzip, zlib (deflate), and deflate. If the request is compressed,
the Content-Encoding header is set to indicate that the content is
compressed. zlib (deflate) represents RFC 1950 + RFC 1951 combined. deflate represents RFC 1951 only. |
requestCompressionType |
The RESTRequest node SSL properties are described in the following table.
| Property | M | C | Default | Description | mqsiapplybaroverride command property |
|---|---|---|---|---|---|
| Protocol | No | Yes | TLS | The SSL protocol to use when making an HTTPS request. | protocol |
| Allowed SSL ciphers | No | Yes | A comma-separated list of ciphers to use when making an SSL request. The default value of an empty string means use all available ciphers. | allowedCiphers | |
| Enable SSL certificate hostname checking | No | Yes | No | This property specifies whether the host name of the server that is receiving the request must match the host name in the SSL certificate. | hostnameChecking |
| SSL client authentication key alias | No | Yes | (empty string) | This property specifies an SSL authentication alias for the client-side of an HTTP connection. Taking the default value means that the first appropriate key is chosen for you automatically. | keyAlias |
| Enable certificate revocation list checking | No | Yes | Not selected | This property specifies whether CRL checking should be enabled for SSL connections | enableCRLCheck |
The RESTRequest node Request properties are described in the following table.
| Property | M | C | Default | Description |
|---|---|---|---|---|
| Parameters | No | No | The parameters table displays the current list of parameters for the operation that is selected on the Basic panel. For each parameter shown, you can specify an XPath or ESQL expression in the Expression column, to specify a value (either a literal or a message tree path) for that parameter. Alternatively, the values for parameters can be provided in the LocalEnvironment. | |
| Content-Type | No | No | The value of the Content-Type header to send
in the request to the REST API. By default, the RESTRequest node determines
a Content-Type to use based on the input message. For example, if
the input message contains an XMLNSC message, the Content-Type header
in the request will be application/xml. You can select
a Content-Type from the REST API definitions file, or you can specify
your own Content-Type. |
|
| Input body location | Yes | No | $Body | The location in the incoming message tree from which data is retrieved to form the HTTP request body that is sent from the RESTRequest node to the REST API. The default value, $Body, represents the incoming message body. You can enter any XPath or ESQL expression that defines the location of the message tree to serialize and send to the REST API. |
The RESTRequest node Response properties are described in the following table.
| Property | M | C | Default | Description |
|---|---|---|---|---|
| Accept | No | No | The value of the Accept header to send in the request to the REST API. By default, the RESTRequest node sends an accept anything value of */*. You can select an Accept from the REST API definitions file, or you can specify your own Accept. | |
| Result body location | No | No | $ResultRoot | This property specifies which subtree of the result to place in the message. If a value is not specified for this property, $ResultRoot is used as the default and the whole response is placed in the output message at the location that is specified in the Output body location property. For more information, see Combining a result message with an input message when fetching data from external systems. |
| Output body location | No | No | $OutputRoot | The message tree location to which the RESTRequest node sends output. The default value, $OutputRoot, replaces the incoming message with the response. For more information, see Combining a result message with an input message when fetching data from external systems. |
| Error body location | No | No | $OutputRoot | The message tree location to which the RESTRequest node sends output when the response is routed to the error terminal (based on the routing conditions described for the error terminal). The default value, $OutputRoot, replaces the incoming message with the response. For more information, see Combining a result message with an input message when fetching data from external systems. |
| Copy local environment | Selected | This property controls whether to copy the incoming local environment or propagate the incoming local environment. By default, this check box is selected, which specifies that the local environment is copied so that the incoming local environment is preserved. The additions to the local environment are visible only to nodes downstream of this node. If this check box is cleared, the incoming local environment is used for the outgoing message. Any modifications that are made to the local environment by this node are visible to both downstream and upstream nodes after this node has completed. | ||
| Accept compressed responses by default | No | Yes | Selected | This property specifies whether the request
node handles compressed responses by default. If the request header
does not contain an Accept-Encoding header, and this option is selected,
the node sets the Accept-Encoding header to gzip, deflate,
and any compressed response that is received is decompressed by the
node. If the message propagated to the RESTRequest node includes an
Accept-Encoding header, the message flow or client application should
handle any compressed response, in which case this property has no
effect. |
The RESTRequest node Response Message Parsing properties are described in the following table.
| Property | M | C | Default | Description |
|---|---|---|---|---|
| Automatic Content-Type handling | No | No | Selected | When this property is selected, the RESTRequest node automatically
selects the message domain to be used to parse the response body,
based on the value of the Content-Type header in the response. For
example, if the Content-Type header in the response is application/json,
the JSON message domain is used. When this property is selected, you
cannot specify any other fields on this panel. |
| Message domain | No | No | BLOB | The domain that is used to parse the message. If the field is blank, the default is BLOB. |
| Message model | No | No | Cleared | The name or location of the message model schema
file in which the message is defined. When you click Browse, you see a list of available message model schema files for the selected Message domain. |
| Message | No | No | Cleared | The name or location of the message root within your message model schema file. This list is populated with all available messages that are defined in the Message model that you have selected. |
| Physical format | No | No | Cleared | The name of the physical format of the message. If you are using the MRM or IDOC parser, select the physical format of the incoming message from the list. This list includes all the physical formats that you have defined for the selected message model. If you set the Message domain property to DataObject, you can set this property to XML or SAP ALE IDoc. Set this property to SAP ALE IDoc when you have to parse a bit stream from an external source and generate a message tree. |
The RESTRequest node Parser Options properties are described in the following table.
| Property | M | C | Default | Description |
|---|---|---|---|---|
| Parse timing | No | No | On Demand | This property controls when a response message
is parsed. Valid values are On
Demand, Immediate,
and Complete. For a full description of this property, see Parsing on demand. |
| Build tree using XML schema data types | No | No | Cleared | This property controls whether the XMLNSC parser creates syntax elements in the message tree with data types taken from the XML schema. You can select this property only if you set the Validate property on the Validation tab to Content or Content and Value. |
| Use XMLNSC compact parser for XMLNS domain | No | No | Cleared | This property controls whether the XMLNSC Compact Parser is used for messages in the XMLNS Domain. If you set this property, the response message data is displayed under XMLNSC in nodes that are connected to the output terminal when the input MQRFH2 header or Response Message Parsing properties Domain is XMLNS. |
| Retain mixed content | No | No | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters mixed text in a response message. If you select the check box, elements are created for mixed text. If you clear the check box, mixed text is ignored and no elements are created. |
| Retain comments | No | No | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters comments in a response message. If you select the check box, elements are created for comments. If you clear the check box, comments are ignored and no elements are created. |
| Retain processing instructions | No | No | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters processing instructions in a response message. If you select the check box, elements are created for processing instructions. If you clear the check box, processing instructions are ignored and no elements are created. |
| Opaque elements | No | No | Blank | This property is used to specify a list of elements in the response message that are to be opaquely parsed by the XMLNSC parser. Opaque parsing is performed only if validation is not enabled (that is, if the Validate property is set to None); entries that are specified in Opaque Elements are ignored if validation is enabled. |
The RESTRequest node Validation properties are described in the following table.
For a full description of these properties see Validation properties.
| Property | M | C | Default | Description | mqsiapplybaroverride command property |
|---|---|---|---|---|---|
| Validate | No | Yes | None | This property controls whether validation takes place. Valid values are None, Content and Value, Content, and Inherit. | validateMaster |
| Failure action | No | No | Exception | This property controls what happens if validation fails. You can set this property only if you set Validate to Content or Content and Value. Valid values are User Trace, Local Error Log, Exception, and Exception List. |
| Property | M | C | Default | Description |
|---|---|---|---|---|
| Events | No | No | None | Events that you have defined for the node are
displayed on this tab. By default, no monitoring events are defined
on any node in a message flow. Use Add, Edit,
and Delete to create, change or delete monitoring
events for the node; see Configuring monitoring event sources by using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box. |
Local environment overrides
You can dynamically override set values in the local environment in the same way as setting values in other elements of a message. For more information, see Using local environment variables with REST nodes.