public interface ServerRestConnector
RestDataSource
implementation;
the client-side dataSource is intended for cases where you are creating the server API and
thus have control over the format and protocols used, but you do not wish to use the
Smart GWT Server for some reason. The server-side implementation, which is documented
below, is intended for cases where you need to connect to existing third-party REST APIs
(which, despite the impression that "REST" is a standardized approach, vary significantly
from one to the other in their details)
RestConnector is a built-in server-side DataSource
implementation. It is able to convert a standard client-submitted or server-created
DSRequest into an arbitrary REST webservice call,
and convert the
REST service response into a standard DSResponse.
These conversions
are highly configurable, making use of any or all of the following:
Record-level and field-level
XPath processingVelocity-based templates providing
powerful declarative data
templating and conversion for both requests and
responses. These
templates are evaluated at request/response
execution time, so can include dynamic elements such as the criteria sent from the clientrequests and
responses at the
record-level, and for response
data at the field-levelRestController was designed to be as flexible and configurable as possible.
One of the ways we achieve this is with pervasive support for Velocity templating. In the
descriptor (*.ds.xml file) of a RestController dataSource, you can use Velocity
expressions in any element, and they will be replaced at execution time. This means that
you can embed references to server.properties items, elements from the values
and criteria of this operation, elements of other useful context objects, and arbitrary
values that your code has set up in the Velocity template context (see the
Velocity overview for details of these latter
two). See the
sample config below for examples of how this feature can be used. Additional examples are
also shown in the docs of individual config properties (headers,
for example)
Important: Because we allow references to $criteria and
$values in RestConnector config, it follows that we re-evaluate
Velocity expressions on every DSRequest; in fact, as the following section
discusses, when there are multiple valueSets, we evaluate Velocity expressions multiple
times per DSRequest. However, we do not evaluate $config
references per-DSRequest: $config references are evaluated during
DataSource initialization, and are fixed thereafter. The main implication of
this is, if you are pooling and reusing DataSource instances (which is the
default), $config references will be fixed after initial evaluation for the
life of the JVM, so you should not expect to be able to change a config setting and have it
picked up in RestConnector Velocity templates.
RestController has a general ability to handle multiple valueSets, but only
for REST services where both the requestFormat and the
responseFormat are "json".
For example, if we receive a
dsRequest with two valueSets, like this:
[
{name:"Smith", ID:72},
{name:"Jones", ID:1044}
]
We will combine those two records into a single JSON block to send to the remote REST
server:
[{"name":"Smith","ID": 72},{"name":"Jones","ID":1044}]
RestConnector is also able to wrap singular records in a list, for remote
services that want to treat all input as a list - see wrapInList
Request templates are also
able to handle multiple
valueSets. If there are multiple valueSets in the DSRequest, or if
wrapInList is in force, we will apply each valueSet to the template,
constructing a list of templated JSON blocks to send to the REST server.
As noted, RestConnector is flexible enough that it is able to connect with
REST APIs that use non-standard authentication techniques, such as embedding a token
or username/password credentials in the request body. These non-standard authentication
approaches are found more often than might be thought, and although they are non-standard,
they are not any less secure than the standard approaches as long as you are using HTTPS.
See the auth block documentation for
full details.
serverConfig
block of a DataSource descriptor (.ds.xml file) - the client has no need to
know about this configuration, and generally should not be able to see it - although
serverConfig is optional in nearly every cases; see the serverConfig
documentation for details of this.
An example configuration is shown below.
<DataSource
ID="SomeRestDataSource"
serverType="rest"
>
<serverConfig>
<requestFormat>params</requestFormat>
<responseFormat>json</responseFormat>
<recordXPath>items</recordXPath>
<!-- This is the default URL to send REST requests to, if not overridden at the
OperationBinding level. Note, this MUST be declared inside the serverConfig
block, otherwise client code in the browser will try to use it. This example
just uses plain, untemplated config but there are lots more options - see the
operationBindings below -->
<dataURL>https://somerestservice.com/api/search</dataURL>
<auth>
<type>basic</type>
<username>$config['rest.somerestservice.apiUser']</username>
<password>$config['rest.somerestservice.apiToken']</password>
</auth>
<operationBindings>
<operationBinding operationType="fetch" operationId="customerFetch">
<!-- You can use values defined in your server.properties file with the
"$config" context variable -->
<dataURL>$config['rest.somerestservice.baseURL']/customers</dataURL>
</operationBinding>
<operationBinding operationType="update" operationId="updateCustomer">
<!-- And you can use values and criteria sent up from the client with "$values"
and "$criteria" -->
<dataURL>$config['rest.somerestservice.baseURL']/customer/$criteria['customerId']?name=$values['custName']</dataURL>
<requestFormat>json</requestFormat>
</operationBinding>
<operationBinding operationType="remove">
<!-- And you can use arbitrary values placed in the template context, as with
"$deletePath" here -->
<dataURL>$config['rest.somerestservice.baseURL']/$deletePath/$values['itemKey']</dataURL>
</operationBinding>
</operationBindings>
</serverConfig>
</DataSource>
RESTRequestFormat,
RESTResponseFormat,
RESTAuthenticationType,
com.smartgwt.client.data.RESTAuthentication,
DataSource.serverConfig,
DataSource.headers,
OperationBinding.headers,
DataSource.params,
OperationBinding.params,
DataSource.httpMethod,
OperationBinding.httpMethod,
DataSource.requestFormat,
OperationBinding.requestFormat,
DataSource.responseFormat,
OperationBinding.responseFormat,
DataSource.wrapInList,
OperationBinding.wrapInList,
DataSource.xmlTag,
OperationBinding.xmlTag,
DataSource.csvDelimiter,
OperationBinding.csvDelimiter,
DataSource.csvQuoteCharacter,
OperationBinding.csvQuoteCharacter,
DataSource.suppressAutoMappings,
OperationBinding.suppressAutoMappings,
DataSource.requestTemplate,
OperationBinding.requestTemplate,
DataSource.responseTemplate,
OperationBinding.responseTemplate,
DataSource.requiresCompleteRESTResponse,
OperationBinding.requiresCompleteRESTResponse,
DataSource.auth,
RESTAuthentication.type,
RESTAuthentication.username,
RESTAuthentication.password,
RESTAuthentication.authToken,
RESTAuthentication.authHeader,
RESTAuthentication.dataSource