Configuring the RESTful Web Service¶
This section explains how to configure several settings of the global RESTful web service (i.e. the service at http://denodo-server.acme.com:9090/denodo-restfulws).
This section is not about the settings of REST web services (i.e. services that publish a specific set of views).
Limit the Maximum Number of Rows Returned¶
You can limit the maximum number of rows returned by the RESTful web service. That is, 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 set this limit, follow these steps:
Stop all the Denodo servers. The goal is to make sure the web container is stopped.
Edit the file
other_settings.xml
of the folder<DENODO_HOME>/resources/apache-tomcat/webapps/denodo-restfulws/WEB-INF/
Set the value of the property
maximumRowsPerPage
to the limit you want to set.Start the Denodo servers.
Changes to this file will be preserved even when an update of the Denodo Platform is installed.
Design Studio provides graphical support to configure this limit on REST web services (the ones that only publish a set of views). The section Settings Tab (REST) explains how to do this.
Limit the Memory Used When Generating Response¶
Some configurations applied to the web service may require to store the result in memory until the full response is generated. This is the case for returning pagination information as HTTP headers and for enabling RFC 7807 errors while paginating results. The main reason is that HTTP headers and status code should be setted before the response is being sent to the client so no rows streaming can be done in the previous scenarios. To prevent this features to use more memory than expected you can enable a memory limit by following these steps:
With the web container stopped, edit the file
<DENODO_HOME>/resources/apache-tomcat/webapps/denodo-restfulws/WEB-INF/other_settings.xml
Add the following
env-entry
section<env-entry> <env-entry-name>resultMemoryLimit</env-entry-name> <env-entry-type>java.lang.Integer</env-entry-type> <env-entry-value>100</env-entry-value> </env-entry>
Set a value in MB for the maximum size for each HTTP response generation. A value of 0 will disable the limit
Note
By default published web services already use the query memory limit configured at the server. A custom value (in MB) can also be specified with the following property:
SET 'com.denodo.wsgenerator.rest.memoryLimit'='<value in MB>';
You can disable the limit by setting the following property:
SET 'com.denodo.wsgenerator.rest.enableMemoryLimit'='false';
Cross-origin Resource Sharing (CORS)¶
The RESTful web service provides support for Cross-origin resource sharing (Cross-Origin Resource Sharing (CORS)). The section Cross-origin Resource Sharing (CORS) (settings of published REST web services) explains in more details what CORS is.
To enable the CORS support on the global RESTful web service, follow these steps:
Do the steps of the section Initial Set-Up of CORS (you have done this already if you published a Denodo REST web service with CORS enabled).
Before starting any server of this Denodo installation, edit the file
<DENODO_HOME>/resources/apache-tomcat/webapps/denodo-restfulws/WEB-INF/cors_settings.xml
Uncomment the contents of the file.
If the value of the property is *, the Service will allow CORS requests received from any domain.
To limit the domains from which CORS requests are allowed, change the value of the property
cors.allowOrigin
; replace * with the list of allowed URLs. Separate each URL by a comma.For example,
https://foo.com, http://foo.com, https://foo.bar.com
CORS requests from any other origin will be denied with the HTTP code 403 (Forbidden)
Important
For each URL, enter its protocol as well. URLs that not contain the protocol are invalid. E.g. foo.com is invalid.
Start the Denodo servers.
Changes to this file will be preserved even when an update of the Denodo Platform is installed.
This change only affects the global RESTful web service. If you want to publish REST web services with CORS support, see the section Cross-origin Resource Sharing (CORS) (settings of published REST web services).
Customizing the Look & Feel of the RESTful Web Service¶
The RESTful web service and the REST web service show the logo of the Denodo Platform at the top.
To replace the Denodo logo with another logo, follow these steps:
Note
This affects the RESTful web service and all the REST web services deployed after doing this change.
Copy the new logo to the directory
<DENODO_HOME>/resources/apache-tomcat/webapps/denodo-restfulws/resources/
.Edit the file
stylesheet-customizable.css
of the directory<DENODO_HOME>/resources/apache-tomcat/webapps/denodo-restfulws/resources/
Uncomment the CSS definition
div#page-header
.In this definition, replace the URL of the attribute
background-image
with the URL of the new logo.You should end up with a CSS definition similar to this one:
div#page-header { background-image: url('/denodo-restfulws/resources/new_logo.png'); background-position: top left; background-repeat: no-repeat; height: 45px; padding-bottom: 25px; position: relative; width: 85%; height: 80px; }
These changes are effective immediately; you do not need to restart. You may need to refresh the cache of the browsers.
Changes to this file will be preserved even when an update of the Denodo Platform is installed.
After following the steps above, all the REST web services that you deploy or redeploy and that do not have its CSS definition customized, will use this new CSS definition. Therefore, they will display the new icon instead of the Denodo one.
Customizing RESTful Web Service to Return Pagination Information as HTTP Headers.¶
By default the RESTful Web Service provides pagination information in the response by adding the links to previous/next page. This allows VDP to stream results from the beginning and add the pagination information when the result has been processed.
For receiving the pagination information as HTTP Headers configure the following:
With the web container stopped, edit the file
<DENODO_HOME>/resources/apache-tomcat/webapps/denodo-restfulws/WEB-INF/other_settings.xml
Locate or add the following
env-entry
section<env-entry> <env-entry-name>enablePaginationHeaders</env-entry-name> <env-entry-type>java.lang.Boolean</env-entry-type> <env-entry-value>FALSE</env-entry-value> </env-entry>
Update the value to TRUE
Note
If you want to apply this setting to published web services on VDP you must set the following property on VDP:
SET 'com.denodo.wsgenerator.restws.enablePaginationHeaders'='true';
This configuration will return the following HTTP headers when using pagination on RESTful Web Services:
pagination-index
: The index of the first result returned on this page.pagination-count
: The requested number of results on this page.pagination-page-results
: The actual number of results returned in this page (the value would be equals to pagination-count except on the last page that may be lower).
There is also the possibility to rename the headers using a JSON mapping by configuring the following:
With the web container stopped, edit the file
<DENODO_HOME>/resources/apache-tomcat/webapps/denodo-restfulws/WEB-INF/other_settings.xml
Locate or add the following
env-entry
section<env-entry> <env-entry-name>paginationHeadersMapping</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>{}</env-entry-value> </env-entry>
Update the value to specify the mapping of names in JSON format. For example:
{"pagination-page-results":"pageresults", "pagination-index":"pageindex", "pagination-count":"pagecount"}
<env-entry> <env-entry-name>paginationHeadersMapping</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>{"pagination-page-results":"pageresults", "pagination-index":"pageindex", "pagination-count":"pagecount"}</env-entry-value> </env-entry>
Note
If you want to apply this setting to published web services on VDP you must set the following property on VDP with the JSON:
SET 'com.denodo.wsgenerator.restws.paginationHeadersMapping'='{<mapping JSON>}';
Follow RFC 7807 Specification on HTTP Errors¶
By default the RESTful web service and deployed web services returning an error do generate a custom error message. The
response Content-Type
is also the same as when an HTTP 200 status is returned (application/json
for example).
In RFC 7807 there is a definition of a standard way to return problems in HTTP REST
responses for JSON and XML messages. This RFC describes how the response should contain an application/problem+json
or
application/problem+xml
as Content-Type
. It does also provide requirements and recommendations about the error message structure.
You can enable the RESTFul web service to follow RFC 7807 specification by doing the following:
With the web container stopped, edit the file
<DENODO_HOME>/resources/apache-tomcat/webapps/denodo-restfulws/WEB-INF/other_settings.xml
Locate or add the following
env-entry
section<env-entry> <env-entry-name>restfulErrorsAsApplicationProblem</env-entry-name> <env-entry-type>java.lang.Boolean</env-entry-type> <env-entry-value>FALSE</env-entry-value> </env-entry>
Update the value to TRUE
Note
If you want to apply this setting to published web services on VDP you must set the following property on VDP:
SET 'com.denodo.wsgenerator.restws.restfulErrorsAsApplicationProblem'='true';
Once this setting is enabled the response error messages will change its structure and this will be reflected also in the OpenAPI specification. Check the following samples on how the error is being formatted:
Authentication error as application/problem+json
:
{ "type":"http://www.denodo.com/restful/error/http/401/vdp/-1", "title":"Unauthorized", "status":401, "code":-1, "detail":"You are not authorized to access this resource", "__errors__":[ { "message":"You are not authorized to access this resource" } ] }
Authentication error as application/problem+xml
:
<problem xmlns="urn:ietf:rfc:7807"> <type>http://www.denodo.com/restful/error/http/401/vdp/-1</type> <title>unauthorized</title> <status>401</status> <code>-1</code> <detail>you are not authorized to access this resource</detail> <__errors__> <error message="you are not authorized to access this resource"></error> </__errors__> </problem>
Customizing Request Parameter Names in RESTFul web service¶
By default the RESTful web service and deployed web services require a set of predefined input parameters defined in the table Parameters supported by the Denodo RESTful Web service and published REST Web services.
You can define a mapping to rename the query parameters in the RESTFul web service by doing the following:
With the web container stopped, edit the file
<DENODO_HOME>/resources/apache-tomcat/webapps/denodo-restfulws/WEB-INF/other_settings.xml
Locate or add the following
env-entry
section<env-entry> <env-entry-name>restfulParameterNamesMapping</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>{}</env-entry-value> </env-entry>
Update the value to specify the mapping of names in JSON format. To rename
$format
toformat
and$count
tonumber_of_results
you need to add the following value:{"$format":"format", "$count":"number_of_results"}
<env-entry> <env-entry-name>restfulParameterNamesMapping</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>{"$format":"format", "$count":"number_of_results"}</env-entry-value> </env-entry>
By doing this you can use the mapped names in the invocation query. The OpenAPI specification and pagination links will also reflect the new names configured.
Note
If you want to apply this setting to published web services on VDP you must set the following property on VDP with the JSON:
SET 'com.denodo.wsgenerator.restws.restfulParameterNamesMapping'='{<mapping JSON>}';
Modifying the Connection Parameters Between the RESTful Web Service and Virtual DataPort¶
As any client of Virtual DataPort, the RESTful web service has its own connection parameters. In most situations, the default connection parameters of the service are fine, but there may be scenarios where you need to change them. For example, let us say that you are going to query views that take a long time to respond. The default query timeout of this service is fifteen minutes. If you think that some queries may take longer, increase it by following these steps:
Stop all the Denodo servers. The goal is to make sure the web container is stopped.
Edit the file
connection_settings.xml
of the folder<DENODO_HOME>/resources/apache-tomcat/webapps/denodo-restfulws/WEB-INF/
.Increase the value of the property
queryTimeout
. Note the value of this property is in milliseconds.You can also modify other properties of this file if you need to. Each property has a comment above explaining it.
Start the Denodo servers.
Changes to this file will be preserved even when an update of the Denodo Platform is installed.
This change only affects the global RESTful web service. Each REST web service has its own connection parameters.
Important
Do not modify the web.xml of the RESTful web service (that is <DENODO_HOME>/resources/apache-tomcat/webapps/denodo-restfulws/WEB-INF/web.xml
) because the next time you install an update of Denodo, this file will be overwritten. You can do changes to the files “connection_settings.xml”, “cors_settings.xml” and “other_settings.xml”; when installing an update, these files are not modified.
Modify the RESTful Web Service to return only the result set on XML/JSON response.¶
By default the RESTful Web Service returns execution results grouping metadata information like view name, data and errors. In some environments it may be required to get only data as an array without additional information.
To enable this behavior you must configure the following:
With the web container stopped, edit the file
<DENODO_HOME>/resources/apache-tomcat/webapps/denodo-restfulws/WEB-INF/other_settings.xml
Locate or add the following
env-entry
section<env-entry> <env-entry-name>hideRestfulMetadataOnResult</env-entry-name> <env-entry-type>java.lang.Boolean</env-entry-type> <env-entry-value>FALSE</env-entry-value> </env-entry>
Update the value to TRUE
Note
If you want to apply this setting to published web services on VDP you must set the following property on VDP:
SET 'com.denodo.wsgenerator.restws.hideRestfulMetadataOnResult'='true';
Examples:
XML example:
{ "name": "testfail", "elements": [ { "field":"value" }, { "field":"value" }, ] }Will change to:
[ { "field":"value" }, { "field":"value" }, ]
XML example:
<denodo:view name="<view_name>" xmlns="..."> <view_name> <rowdata/> </view_name> <view_name> <rowdata/> </view_name> </denodo:view>Will change to:
<denodo:view xmlns="..."> <item> <rowdata/> </item> <item> <rowdata/> </item> </denodo:view>