Creating REST Web Services¶

The REST Web services publish the data of one or more views and optionally the associations between those views (see section Associations). These services follow the same RESTful approach as the Denodo RESTful Web service and work in the same way with the difference that they only display the data of the views and associations you choose.

The main difference with the SOAP Web services is that REST Web services are “resource-oriented” and the SOAP ones are “operation-oriented”.

The REST Web services provide four different representations of the data:

• HTML

• XML

• JSON

• RSS. This is only available if you configure the Service with the RSS MAPPING VIEW clause

CREATE [ OR REPLACE ] REST WEBSERVICE <name:identifier>
    [ PRESERVE_OPERATIONS ]
    CONNECTION (
        CHUNKSIZE = <integer>
        CHUNKTIMEOUT = <integer>
        QUERYTIMEOUT = <integer>
        POOLENABLED = <boolean>
        POOLINITSIZE = <integer>
        POOLMAXACTIVE = <integer>
    )
    [ DEFAULTREPRESENTATION = <representation> ]
    [ SUPPORTEDREPRESENTATIONS = ( <representation> [, <representation> ]* ) ]
    [ DISPLAYRESTFULREFERENCES = { TRUE | FALSE } ]
    [ AUTHENTICATION ( <authentication> ) ]
    [ CUSTOMNAMESPACE = <literal> ]
    [ CUSTOMCSS = <css stylesheet:literal> ]
    [ VERBOSEERRORS = <boolean> ] // Default value is true
    RESOURCES ( <resource config> [, <resource config> ]* )
    [ ASSOCIATIONS ( <association name:identifier with database>
                     [, <association name:identifier with database> ]* ) ]
    [ OPTIONS (
        [ <RSS mapping> [, <RSS mapping> ]* ]
        [ <XSLT config> [, <XSLT config> ]* ]
        [ APPLYOUTPUTXSLTTOERRORS ]
        [ NULLVALUESASEMPTYXMLELEMENTS = <boolean> ]
        [ ALLOW_CORS_ORIGINS ( { * | <literal> [, <literal> ]* } )
            { ENABLED | DISABLED } ]
        [ MAX_ROWS_PER_PAGE = <non-zero positive integer> ]
        [ PROCESS_FUNCTIONS_IN_SELECT_PARAMETER = <boolean> ]
      )
    ]
    [ FOLDER = <literal> ]
    [ DESCRIPTION = <literal> ]

<representation> ::=
    HTML
  | JSON
  | RSS
  | XML

<authentication> ::=
    BASIC <credentials>
  | BASIC VDP [ VDPACCEPTEDUSERS <users list> ]
  | DIGEST <credentials>
  | SPNEGO
  | SAML2 <saml2 parameters>

<credentials> ::=
  USER <user name:literal> PASSWORD <password:literal> [ ENCRYPTED ]

<users list> ::=
  <user name:literal> [, <user name:literal> ]*

<saml2 parameters> ::=
  SPENTITYID <service provider entity ID:literal>

<resource config> ::=
  VIEW <view identifier>
  FIELDS ( <fields list> [ <fields' mappings> ] )

<fields list> ::= <field> [, <field> ]*

<field> ::=
  <name:literal> : <type:literal>
  [ <XPath of the field:literal> = <displayed name:literal> ]
  [ <direction> ] [ OBL ] [ UNESCAPED ]

<direction> :: =
    INPUT_ONLY
  | OUTPUT_ONLY }

<RSS mapping> ::=
  RSS MAPPING VIEW <viewName:literal> (
    CHANNEL ( <mapping> [, <mapping> ]* )
    ITEM ( <item mapping> [, <item mapping> ]* )
  )

<mapping> ::=
  <rss tag:literal> = <value:literal>

<item mapping> ::=
  <rss tag:literal> = <field:identifier>

<XSLT config> ::=
  VIEW <viewName:literal> XSLT (
    [ INPUTXSLT = <XSLT:literal> { ENABLED | DISABLED } ]
    [ OUTPUTXSLT = <XSLT:literal> { ENABLED | DISABLED } ]
  )

<view identifier> ::= (see Basic elements of VQL statements)

<identifier with database> ::= (see Basic elements of VQL statements)

You have to define the views you want to publish in the RESOURCES clause. For each view you publish, you have to indicate its name after the VIEW clause and the fields of the view (FIELDS). You are not forced to publish all the fields of the view.

To publish associations, add the ASSOCIATIONS parameter, which is a comma-separated list of the names of the associations you want to publish.

The parameters CHUNKSIZE, CHUNKTIMEOUT, QUERYTIMEOUT, POOLENABLED, POOLINITSIZE and POOLMAXACTIVE configure the connection between the Web service and the Virtual DataPort server (see section Connection Parameters)

The parameters DEFAULTREPRESENTATION and SUPPORTEDREPRESENTATIONS set the default representations and the available representations of the Web service (see section Selecting the Default / Available Representations of the Administration Guide).

If you do not want the Web service to return verbose error messages, add the clause VERBOSEERRORS = false. If you do not add this clause or set it to true, the Web service will return verbose error messages when there is an error invoking one of its operations. These messages indicate where the problem was raised. E.g. if there was a timeout connecting to one of the data sources, an error executing a query, etc. If you do not want the clients of the Web service to get these verbose messages, add VERBOSEERRORS = false.

The parameter DISPLAYRESTFULREFERENCES corresponds with the check box “Display RESTful links” of the “Create REST Web service” dialog (see section Settings Tab (REST) of the Administration Guide). If it is FALSE, at runtime, the Web service will not return the links of the view.

In the definition of each field, the following modifiers correspond to the status of a field:

• OBL: mandatory field

• INPUT_ONLY: Do not output

• OUTPUT_ONLY: No searchable.

UNESCAPED indicates that, at runtime, the values of this field will not be HTML-escaped (see section HTML-Escaping the Data of the Administration Guide).

The authentication configuration of the Service is controlled with the AUTHENTICATION parameter.

The RSS format specifies a series of specific fields for each item. 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. This is possible through the MAPPING clause. An RSS feed contains a channel element that specifies general information on the feed. The CHANNEL parameter of the MAPPING clause allows specifying constant values for each of the channel subelements permitted by the RSS format. An RSS feed contains a list of item elements. Virtual DataPort will generate an item element for each tuple returned by the query made on the view used in the service. The ITEM parameter of the MAPPING clause allows selecting the attribute of the view corresponding to each item subelement defined in RSS format. The RSS format specifies that at least one value must be assigned either to the title subelement or to the description subelement.

By default, the XSLT transformations are applied to data but not to the error messages returned by the Web service. Add the clause APPLYOUTPUTXSLTTOERRORS if you want the Service to apply them to error messages as well.

This only affects the XML representation of the Service.

By default, the Denodo REST Web services explicitly specify that a value of a field is NULL by adding the attribute xsi:nil="true" to the element. E.g. if in a row, the value of the field field_name is NULL, the service returns the following:

<field_name xsi:nil="true" />

If you do not want the Web Service to specify NULL values with the attribute xsi:nil="true", add the clause NULLVALUESASEMPTYXMLELEMENTS = TRUE. As a result, NULL values will be represented with an empty element. E.g. <field_name />. The problem of enabling this option is that, for text fields, there is no difference between a NULL value and an empty string.

Not adding this clause is equivalent to adding NULLVALUESASEMPTYXMLELEMENTS = FALSE.

Note that this only applies to the XML representation of the views.

You can enable support for Cross-origin resource sharing (CORS) on a REST Web Service. See more about CORS in the section Cross-origin Resource Sharing (CORS) of the Administration Guide.

To enable this support, add the clause ALLOW_CORS_ORIGINS to indicate from which domains this service can receive requests.

Enter ALLOW_CORS_ORIGINS ( * ) to allow CORS requests from any domain.

Or, enter ALLOW_CORS_ORIGINS ( <list of allowed domains> ) being <list of allowed domains> a comma-separated list of URLs from which requests to this service are allowed. For example, ALLOW_CORS_ORIGINS ( http://foo.com, https://foo.bar.com )

If you set the list of allowed domains, any CORS request from any other domain will be denied with the HTTP code 403 (Forbidden)

You can limit the maximum number of rows returned by the service. If this limit is enabled, when a client queries a view, the number of rows in the response will never exceed this limit. This feature is useful to make sure that there is not any client who puts too much strain on the Virtual DataPort server or its data sources.

To enable this limit, add the parameter MAX_ROWS_PER_PAGE = <non-zero positive integer> to the OPTIONS clause.

Adding the parameter PROCESS_FUNCTIONS_IN_SELECT_PARAMETER = TRUE is equivalent to selecting the check box Process functions in $select parameter of the tab Advanced, in the configuration of the REST web service in the administration tool.

The section Advanced Tab (REST) of the Administration Guide explains this option.

In an environment with existing REST clients and services, we do not need to modify those clients to work with Virtual DataPort Web services. We can define XSLT stylesheets to transform the incoming XML messages to adapt them to the format that the new Web service expects. We also can define stylesheets to transform the XML responses before sending them to the existing clients. To do this, use the parameter XSLT.

For more information about this, read the section XSLT Transformations of the Administration Guide.

PRESERVE_OPERATIONS clause can be used only with a CREATE OR REPLACE operation. The token indicates that if exists a web service with the same name, its resources will be preserved and replaced when resource name conflict.