Interface ServerRestConnector
Server-side REST Connector
NOTE: This article discusses Smart GWT's server-side REST client implementation. It should not be confused with the client-sideRestDataSource
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-levelandfield-levelXPath processingVelocity-basedtemplates providing powerful declarative data templating and conversion for bothrequestsandresponses. These templates are evaluated at request/response execution time, so can include dynamic elements such as the criteria sent from the client- Where declarative conversion is not sufficient, inline scripts written in Groovy,
Javascript
or other JSR-223 languages can add conversion of arbitrary complexity. Again, we support
scripts for converting both
requestsandresponsesat the record-level, and for response data at thefield-level
Pervasive Velocity support
RestController 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.
Multiple ValueSets
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.
Authentication
RestConnector provides the following standard authentication methods:- Basic Authorization with a username and password or API token
- Bearer Authorization with an API token
- Bearer Authorization with a refresh/access token scheme, such as JSON Web Tokens (JWT)
- Manually-constructed Authorization header
- Ad-hoc, informal auth schemes, like embedding an API token in the body of the request
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.
Example configuration
RestConnector configuration is typically expressed in theserverConfig
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>
- See Also:
-
RESTRequestFormatRESTResponseFormatRESTAuthenticationTypecom.smartgwt.client.data.RESTAuthenticationDataSource.serverConfigDataSource.headersOperationBinding.headersDataSource.paramsOperationBinding.paramsDataSource.httpMethodOperationBinding.httpMethodDataSource.requestFormatOperationBinding.requestFormatDataSource.responseFormatOperationBinding.responseFormatDataSource.wrapInListOperationBinding.wrapInListDataSource.xmlTagOperationBinding.xmlTagDataSource.csvDelimiterOperationBinding.csvDelimiterDataSource.csvQuoteCharacterOperationBinding.csvQuoteCharacterDataSource.suppressAutoMappingsOperationBinding.suppressAutoMappingsDataSource.requestTemplateOperationBinding.requestTemplateDataSource.responseTemplateOperationBinding.responseTemplateDataSource.requiresCompleteRESTResponseOperationBinding.requiresCompleteRESTResponseDataSource.authRESTAuthentication.typeRESTAuthentication.usernameRESTAuthentication.passwordRESTAuthentication.authTokenRESTAuthentication.authHeaderRESTAuthentication.dataSource