Skip to main content
Version: 2.18.x.x LTS

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, POST, PUT and DELETE requests. All requests can carry data in the form of query and matrix parameters. In addition, 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

NameType, usage constraints, defaultsDescription
connectionPoolrequired: paraVal
default: none
type: HttpConnectionPool
HTTP connection pool to be used
urlrequired: paraVal
default: none
type: URL
URL of the service resource
commandoptional: paraVal
default: GET
type: GET, HEAD, PATCH, POST, PUT, DELETE
HTTP method or command to request on the resource
queryParametersoptional: 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
matrixParametersoptional: 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
messageFormatoptional: 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.
contentoptional: 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.
headersoptional: paraMap
default: none
type: string/string
Additional headers for the HTTP request
expectedStatusoptional: 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.
iteratorrequired: 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.
datarequired: 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.
xpathNamespacesoptional: 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.
encodingoptional: 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">

</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>