Version: 8.2411.x.x RR

RestDataSource

The RestDataSource is used to interact with REST-ful web services and to consume their responses. It uses HTTP as a transport layer and can issue GET, HEAD, PATCH, POST, PUT and DELETE requests. All requests can carry data in the form of query and matrix parameters. In addition, PATCH, POST and PUT requests can carry content which is transferred to the service. Expressions can be used to extract data from the response. Two different message formats are supported: XML and JSON. An iterator expression is used to define the elements over which RestDataSource loops. Data expressions are used to extract the data fields from the element of the current iteration.

For XML messages, x-path expressions are used to define the iterator and data expressions.
For JSON messages, JsonPath is used to define the iterator and data expressions.

Configuration

Name	Type, usage constraints, defaults	Description
connectionPool	required: paraVal default: none type: HttpConnectionPool	HTTP connection pool to be used
url	required: paraVal default: none type: URL	URL of the service resource
command	optional: paraVal default: GET type: GET, HEAD, PATCH, POST, PUT, DELETE	HTTP method or command to request on the resource
queryParameters	optional: paraMap default: none type: string/string	Defines the query parameters that are encoded in the URL.Query parameters are parameters which are encoded in the URL after a `?` and which are concatenated with `&`. Example: `<http://url>?param1=value1&param2=value2`
matrixParameters	optional: paraMap default: none type: string/string	Defines the matrix parameters that are encoded in the URL.Matrix parameters are parameters which are encoded in the URL after a `;` and which are concatenated with `;`. Example: `<http://url>;param1=value1;param2=value2`
messageFormat	optional: paraVal default: XML type: XML or JSON	Defines the format of the messages transported and received through HTTP.The Content-type and Accept HTTP headers are automatically set to the correct values: `XML`: application/xml `JSON`: application/json. The headers can be overwritten using the "headers" parameter.
content	optional: paraList default: none type: list of strings	The content that is sent in the body of the HTTP protocol. The content should reflect what was specified as message format. The values of the list are concatenated to form the content. Only the PATCH, POST and PUT methods can carry content in the HTTP body. Therefore, this parameter is only available for PATCH, POST and PUT requests.
headers	optional: paraMap default: none type: string/string	Additional headers for the HTTP request
expectedStatus	optional: paraVal default: 200 type: int	The expected status code of the HTTP response. 200 (OK) is used as default. If the response's status code does not match the expected code, an error occurs.
iterator	required: paraVal default: none type: x-path or JsonPath	The expression is evaluated to extract the elements from the HTTP response over which the `RestDataSource` iterates. The format of the expression depends on the message format: `XML`: X-path expressions `JSON`: JsonPath expressions.
data	required: paraMap default: none type: key/xpath or JsonPath	The expressions are evaluated for every element over which the `RestDataSource` iterates. The extracted data is stored under the specified key in the input object. The format of the expression depends on the message format: `XML`: X-path expressions `JSON`: JsonPath expressions.
xpathNamespaces	optional: paraMap default: none type: string/string (uri)	Register namespace prefixes to the specified URIs. These prefixes are used to parse the XPath expressions. The URIs specified have to match the URIs in the XML document.This is only used for the XML message format.
encoding	optional: paraVal default: default encoding type: string	The name of the character set that should be used to encode the request/response. The available values depend on the version and vendor of the JVM. Examples: UTF-8, ISO-8859-1, UTF-16LE

Example

Query a REST-ful web service using the GET method in either:

XML format

<dataSource type="RestDataSource">
  <dp:paraVal name="connectionPool" value="${inst.httpConnection}"/>
  <dp:paraVal name="url" value="http://resttest/person"/>
  <dp:paraVal name="command" value="GET" />
  <dp:paraVal name="messageFormat" value="xml"/>
  <dp:paraVal name="iterator" value="//person"/>
  <dp:paraMap name="data">
    <value name="street" value="./address[1]/street/text()" />
    <value name="lastname" value="./lastName/text()" />
  </dp:paraMap>
</dataSource>

JSON format

<dataSource type="RestDataSource">
  <dp:paraVal name="connectionPool" value="${inst.httpConnection}"/>
  <dp:paraVal name="url" value="http://resttest/person"/>
  <dp:paraVal name="command" value="GET" />
  <dp:paraVal name="messageFormat" value="json"/>
  <dp:paraVal name="iterator" value="$"/>
  <dp:paraMap name="data">
    <value name="street" value="$.address[0].street" />
    <value name="lastname" value="$.lastName" />
  </dp:paraMap>
</dataSource>

Post some data to a REST-ful web service in either:

XML format

<dataSource type="RestDataSource">
    <dp:paraVal name="connectionPool" value="${inst.httpConnection}"/>  
    <dp:paraVal name="url" value="http://resttest/person"/>
    <dp:paraVal name="command" value="POST" />
    <dp:paraList name="content">
        <value><![CDATA[<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
            <person>
                <lastName>Schmid</lastName>
            </person>]]></value>
    </dp:paraList>
    <dp:paraVal name="messageFormat" value="xml"/>
    <dp:paraVal name="iterator" value="//person"/>
    <dp:paraMap name="data">
        <value name="street" value="./address[1]/street/text()" />
        <value name="lastname" value="./lastName/text()" />
    </dp:paraMap>
</dataSource>

JSON format

<dataSource type="RestDataSource">
    <dp:paraVal name="connectionPool" value="${inst.httpConnection}"/>
    <dp:paraVal name="url" value="http://resttest/person"/>
    <dp:paraVal name="command" value="POST" />
    <dp:paraList name="content">
        <value><![CDATA[{ "lastName":"Schmid"}]]></value>
    </dp:paraList>
    <dp:paraVal name="messageFormat" value="json"/>
    <dp:paraVal name="iterator" value="$"/>
    <dp:paraMap name="data">
        <value name="street" value="$.address[0].street" />
        <value name="lastname" value="$.lastName" /></dp:paraMap>
</dataSource>

Use query parameters to query data from a service using the GET method and XML:

<dataSource type="RestDataSource">
    <dp:paraVal name="connectionPool" value="${inst.httpConnection}"/>
    <dp:paraVal name="url" value="http://resttest/person"/>
    <dp:paraMap name="queryParameters">
        <value name="id" value="1234" />
    </dp:paraMap>
    <dp:paraVal name="command" value="GET" />
    <dp:paraVal name="messageFormat" value="xml"/>
    <dp:paraVal name="iterator" value="//person"/>
    <dp:paraMap name="data">
        <value name="lastname" value="./lastName/text()" />
        <value name="firstname" value="./firstName/text()" />
    </dp:paraMap>
</dataSource>

This works analogous for matrix parameters.

Use an additional „Authorization” header:

<dataSource type="RestDataSource">
    <dp:paraVal name="connectionPool" value="${inst.httpConnection}"/>
    <dp:paraVal name="url" value="http://resttest/person"/>
    <dp:paraVal name="command" value="GET" />
    <dp:paraVal name="messageFormat" value="xml"/>
    <dp:paraMap name="data">
        <value name="Authorization" value="basic dXNlcjpzZWNyZXQK" />
    </dp:paraMap>
    <dp:paraVal name="iterator" value="//person"/>
    <dp:paraMap name="data">
        <value name="street" value="./address[1]/street/text()" />
        <value name="lastname" value="./lastName/text()" />
    </dp:paraMap>
</dataSource>

RestDataSource

Configuration​

Example​

Configuration

Example