Publishing Web Services¶
This section is about the Web services created with previous version of the Denodo Platform.
To publish a view or a stored procedure, right-click on it in the Server Explorer and click Web service on the New > Data service menu.
You can also publish the result of any VQL query by clicking Web service on the New > Data service menu and then, clicking Publish from VQL expression.
The dialog to create new “publishable” Web services has five tabs:
- Operations: select the view/stored procedures published by this Web service. See section Operations Tab.
- SOAP: manage the configuration of the SOAP version of the Web service. See section SOAP Tab.
- REST: manage the configuration of the REST versions of the Web service: XML, JSON, RSS and HTML. See section REST Tab.
- Advanced: manage advanced configuration options such as the connection between the Web service and the Virtual DataPort Server or date type mappings. See section Advanced Tab (Connection Parameters).
- Metadata: select the target folder of the Web service and provide a description for it.
After configuring everything, click Save to create the Web service. The Tool will display the “Web service container status” table that lists the existing Web services (see section Web Service Container Status Table).
This tab contains the list of operations that this Web service will publish.
In this dialog, you can rename the Web service (only when you are creating it), rename / delete input and output parameters, add pagination support for operations, etc.
To add a new operation, drag a view/stored procedure from the Server Explorer to the dialog. Then, the Tool analyzes its query capabilities and generates the “candidate operations” of the Web service. These operations have these characteristics:
- The input parameters of the generated operations correspond to the fields of the view or the input parameters of the stored procedure. If you have added an operation by entering a query in the Publish from VQL expression dialog, the input parameters are the interpolation variables of the query (see the section Using Interpolation Variables as Custom Sources’ Input Parameters for information about interpolation variables).
- The return value of the
SELECToperations is an array of elements. Each element of this array corresponds to a row of the view and will have one subelement for each field.
- If the view is updateable (see “Inserts, Updates and Deletes over Views”
section in the VQL Guide), the Tool generates operations to
insert, update, and delete rows from this view. More specifically, it
generates the following operations:
- An insert operation with a parameter for each field of the view. The name of the operation will start with “insert” followed by the name of the view.
- A delete operation with a parameter for each field of the view. The name of the operation will start with “delete” followed by the name of the view.
- An update operation with two parameters for each field of the view:
one of the parameters will take the name of the field and the other
will take the name of the field prefixed by “New”.
The parameters with the prefix “New” correspond to the new values
SETclause of the
UPDATEstatement). Those without this prefix are used to choose the tuples to be updated (
WHEREclause of the
UPDATEstatement). The name of the operation will start with “update” followed by the name of the view.
Besides creating operations from views, you can also create operations that return the result of any VQL statement. To do that, click Publish from vql expression and provide the VQL statement. These statements can include interpolation variables that will be considered the input parameters of the Web service operation. See section Execution Context of a Query and Interpolation Strings of the VQL Guide for more information about interpolation variables.
You can modify the operations of the Web service as follows:
- Rename an operation: right-click on the operation and click
By default, input parameters of Web services are case-insensitive.
However, if you rename one, it becomes case-sensitive. That is,
during the invocation of the REST, JSON, HTML and RSS Web services
Parameter1is different from
- Delete an operation: right-click on the operation and click Drop.
- Delete an input parameter of an operation: click Drop alongside the name of the parameter. Depending on the query capabilities of the view (see section Query Capabilities), some operations generated may include mandatory parameters that cannot be deleted.
- Delete a return parameter.
Indicate the operator used to execute the query with the value provided
for this input parameter: click on the current operator and select the
new one. This means that if you select the operator
<= for a
P of an operation
O, when a client invokes this
operation, the query sent to the server will be like this:
SELECT ... WHERE P <= <value>
You can change the operator of several input parameters at once by right-clicking on them and click Change operator. The new operator will be applied to the parameters that can accept the selected operator. To select two or more operations / parameters, hold Ctrl or Shift and click on each operation.
To search for an element in the tree of operations, press Ctrl+F.
When you are defining a Web service with an operation that returns a lot of data, you may want to paginate the results in order to avoid retrieving them all at once. With this feature, a client can request the first thousand results, then the next thousand, then… In addition, a client may be interested in limiting the number of rows returned by the Web service.
The pagination support is added operation by operation. That means that if a Web service has several operations, not all of them may have pagination support.
To add pagination to an operation, right-click on the operation and
click Add pagination. The Tool will add two new parameters to the
START_INDEX (these parameters can be
COUNTlimits the number of rows returned by the operation.
START_INDEXskips the rows of the result from row #
0up to row #
These two parameters are optional and if their value is not present, the operation returns all the results of the operation, at once.
If a client passes the
COUNT parameters, the
operation will return
<COUNT> rows, starting from the row number
<START_INDEX> (the first row is
If a client just passes the
COUNT parameter and not
the Web service will return the first
<COUNT> rows of the result.
If a client just passes the
START_INDEX parameter and not
the Web service will return all the rows of the result from row
If later, you need to remove the pagination support from an operation,
right-click on the input parameters
click on Drop.
There is no graphical support to add pagination to operations created
with Publish from vql expression. For these operations, you have to
add the clauses
OFFSET to the query of the operation.
SELECT * FROM V OFFSET @START_INDEX ROWS FETCH NEXT @COUNT ROWS ONLY;
The section OFFSET, FETCH and LIMIT of the VQL Guide contains more information about these clauses.
Support for CONTEXT variables¶
In Virtual DataPort, views can be created with variables in the selection conditions. At runtime, clients have to provide the values of these variables, in the queries. See more about this in the section Adding Variables to Selection Conditions (GETVAR and SETVAR) of the VQL Guide.
When you create a Web service operation, you may need an input parameter
that at runtime is added as a variable to the
CONTEXT clause of the
query. To do this, click on Add context variable. The Tool will add
a new input parameter called
CONTEXT_VAR that it can be
renamed, as any other parameter.
When invoking the Web service, the input parameters that represent
context variables are optional. At runtime, for each input parameter
that represent a context variable, the Server will add a variable to the
CONTEXT clause of the
SELECT statement. The name of the variable
will be the name of the parameter and the value will be the one provided
by the Web service client.
It is not possible to add context parameters to operations created with
Publish from vql expression. For these operations, you have to add
the variables directly on the
CONTEXT clause in the query of the
SELECT * FROM WEALTHY_CLIENT_BY_STATE CONTEXT ('VAR _var_wealthy_client_income_limit' = '250000')
In this tab, you can configure the following parameters of the SOAP version of the Web service:
- The Web Service style: RPC or DOCUMENT.
- XSLT Transformations. You can define XSLT stylesheets that transform the SOAP requests and responses to adapt them to the requirements of existing SOAP clients. See section XSLT Transformations of Web Services Created with Previous Versions.
- SOAP over JMS. Virtual DataPort can subscribe to a JMS server to listen to SOAP messages. See section SOAP Over JMS.
- Configure the authentication method of the SOAP version of the Web Service. See section Authentication in Web Services Created with Previous Versions.
- To disable the SOAP version of the Web service, clear the SOAP check box.
In this tab, you can configure the following parameters of the REST versions of the Web service:
- Select the output of the REST Web service, which can be:
- XML: the output of the operations is an XML document containing the response.
- RSS. Similar to the XML version, but the output is generated in the RSS format (Really Simple Syndication Format - RSS - version 2.0).
- For each operation, you can:
- Define a Custom Endpoint. By default, an operation is invoked by
encoding the parameters in the query part of the URL. E.g.
http://.../getIncidents?IINC_ID=1&TAX_ID=123… However, you also can customize the endpoint of each operation. See section Defining a Custom Endpoint.
- Define a Custom XML namespace for the XML output of the Web service. Each operation has a default namespace that can be customized.
- Define an XSLT stylesheet to transform the requests and responses to this operation, to adapt them to the requirements of an existing REST-XML client. See section XSLT Transformations of Web Services Created with Previous Versions (only for the XML output).
- Define a Custom Endpoint. By default, an operation is invoked by encoding the parameters in the query part of the URL. E.g.
- Edit the default CSS File (only for HTML output) to customize the appearance of the HTML table that display the results.
- RSS Mappings. The RSS format imposes a series of specific fields for each item of its output. Therefore, on exporting a view in RSS format, the correspondence between the fields of the view and the fields in RSS format must be specified. See section Mappings for the RSS Representation for further details.
- Configure the authentication method of the REST versions of the Web Service. See section Authentication in Web Services Created with Previous Versions.
- Select Use case sensitive input field names if you want the input fields of the REST version of the Web Service to be case sensitive. If cleared, the input parameters are case insensitive. E.g. if the check box is cleared and the service has a parameter called REGION, in the URL you can provide the parameter “REGION” or “ReGiOn” and the service will return a response.
Defining a Custom Endpoint¶
By default, the operations of the REST Web services are invoked by
encoding the parameters in the query part of the URL. E.g.
However, you can customize this URL to provide some parameters in the path part of the URL.
For example, if you publish the view
incidents, whose fields are
inc_type, you can query this
view by invoking the URL
http://.../getIncidents?taxid=123 (see the
section Invoking the Operations of the REST Services for more
information about invoking REST Web services without a custom endpoint).
Now, suppose you define the following custom endpoint for the operation
When a client invokes the URL of this operation, the value of the
parameters prefixed with the character
@ will be added to the
WHERE part of the query sent to the server
will return the result of the query
SELECT * FROM incidents WHERE TAX_ID= '123'
returns the results of the query
SELECT * FROM incidents WHERE TAX_ID = '123' AND INC_TYPE = 3
The custom endpoints have to fulfill these conditions:
The endpoint has to start and end with
The parameter names have to be specified with the character
@followed by the name of the field in the published view the operation queries. The name of the parameter has to be followed by the character
If one of the specified parameters is optional, you do not have to provide a value for it. For example, if you define the custom endpoint:
/getCustomer/name/@FULL_NAME/taxId/@TAX_ID/and the fields
TAX_IDare not required to query the view, you can invoke this operation with the following URLs:
http://.../getCustomer/name/taxId/will return all the data of the view.
http://.../ getCustomer/name/taxId/123/will return the data of the customer with
taxId = 123
http://.../ getCustomer/name/John%20Smith/taxId/will return the data of the customers named “John Smith”
The input parameters not included in the custom endpoint can be specified in the query part of the URL.
Advanced Tab (Connection Parameters)¶
The Web services exported will be installed in an application server (typically in the Web service container embedded in the Denodo Platform). Each time a Web service operation is invoked, it will execute a statement against the Virtual DataPort Server to obtain the required results. It is possible to configure certain connection parameters to be used by the Web service to connect to the Server.
The most important aspect of these settings is the use of a connection pool. If enabled, the connections opened by the Web service to Virtual DataPort are reused. In production environments, the use of the connections pool is strongly recommended.
The configuration parameters of the connection are:
- Chunk Size, Chunk Timeout and Query Timeout. Their meaning is the same as in any other VDP client (see section Access through JDBC of the Developer’s Guide).
- Enable Pool. Select this check box to enable the connection pool.
- Initial Size. Initial number of connections opened by the pool.
- Max Active. Maximum number of connections in the pool. A negative value means there is no limit.
This tab also allows configuring the following:
- The type of data used to publish
datefields. The options are the XML Schema
dateTimedata types. The XML Schema
datetype only considers the day, month and year, whereas the
dateTimealso considers the hour, minute, second and millisecond.
- Old XML output (only applies to the XML output): if selected, the output of the XML Web service is backward compatible with the XML Web services published in Virtual DataPort version 4.6. If not selected the output of the XML service produces a simpler XML document.
- Old SOAP DOCUMENT output (only applies to the SOAP output with DOCUMENT style): if selected, the output of the SOAP Web service is backward compatible with the SOAP Web services published from previous versions of the Denodo Platform.