RESTful Web Service

The RESTful Web service of the Denodo Platform is an HTTP service that publishes the contents of the entire Virtual DataPort server.

Unless explicitly mentioned in the documentation, you can use the RESTful web service in the same way as published REST web services: the input parameters are the same and the output has the same format.

The output of this service can be an XML document, a JSON document or a more user-friendly HTML document.

This web service is deployed in the URL http://localhost:9090/denodo-restfulws and exposes the following types of resources:

Types of resources exposed by the RESTful Web service
Type of Resource URI Format Representation
Databases /<database name> Shows the database description and the list of views in the database, including links to access their schema and their elements.
Views /<database name>/views/<view name> Shows the metadata of the view and lists the elements of the view.
Row of a view /<database name>/views/<view name> /<pk field 1>, <pk field 2> Shows the data of an individual row of a view, if the view has its primary key defined.
Number of rows of a of a result set /<database name>/views/<view name> /$count

Returns the number of rows of the view. It can be used in combination with filters by field and/or the parameter $filter.

See more about obtaining the number of rows of a result set in the section Obtaining the Number of Rows of a Result Set

Metadata of a view /<database name>/views /<view name>/$metadata

Returns the metadata of the view. This includes the description of the view and the URLs to retrieve its schema and its associations.

This URL is only supported in the XML and JSON representations, not the HTML one. This means that to obtain the metadata of a view, you either have to send the appropriate Accept header or add ?$format=xml or ?$format=json to the URL.

Schema of a view /<database name>/views /<view name>/$schema

Returns the schema of the view. This a list of the fields and types of the view.

This URL is only supported in the XML and JSON representations, not the HTML one. This means that to obtain the schema, you either have to send the appropriate Accept header or add ?$format=xml or ?$format=json to the URL.

When you request the schema of a view of a REST web service, not the RESTful web service, consider the following:

  • REST services only return the fields that are published; in the configuration of the service, you may have removed some of the fields of the view.
  • REST services return the names of the fields as they appear in the web service, not the name of the fields in the view; in the configuration of the service, you may have renamed some fields.
Associations /<database name>/views /<view name>/$associations

Returns the associations of the view.

This URL is only supported in the XML and JSON representations, not the HTML one. This means that to obtain the associations, you either have to send the appropriate Accept header or add ?$format=xml or ?$format=json to the URL.

When you request the associations of a view of a REST web service, not the RESTful web service, the service will only return the associations that are published with the service, not all the associations of the view.

Examples of how to invoke the RESTful Web service

  • http://localhost:9090/denodo-restfulws/admin returns the list of views of the database admin.
  • http://localhost:9090/denodo-restfulws/admin/views/customer returns the content of the view customer of the database admin.
  • http://localhost:9090/denodo-restfulws/admin/views/customer/1/orders browses through the mapping orders of the row of the table customer whose primary key is 1.

Additional notes about the URI format of the RESTful Web service

  • URLs are case-sensitive. This means that a view TestView must be invoked with http://.../views/TestView, and not http://.../admin/views/testview.

  • If the value of the primary key contains the character ,, replace it with %2C. This is because the character , separates the values of the primary key with more than one field. E.g. http://.../support/views/viewA/1,value%2Cwith%2Ccommas.

  • If the value of the primary key contains the characters / or \, you will receive a 400 error (bad request). The reason is that by default and for security reasons, the Web container embedded in the Denodo Platform (Apache Tomcat) returns the error 400 (bad request) if the URL contains the characters %2F or %5C. They are the URL-encoded characters for / and \ respectively.

    The appendix Allow URIs with Slash and Backslash in Apache Tomcat explains how to disable this protection. You need to disable it if you need to obtain the data of view contained in a database whose name contains any of these characters.

    After disabling this protection, you can access to an element using its primary key with an URL like this one:

    http://…/support/views/viewA/1,value%2Fwith%2Fslashes

  • String literals must not be quoted, except in the $filter parameter (see section Parameters of the RESTful Web Service to see additional information about the parameters of the RESTful Web service).

Following the RESTful conventions, the statement sent to Virtual DataPort by the RESTful Web service, depends on the HTTP method of the request.

The table RESTful Web service: HTTP methods and their equivalent VQL statements displays the type of query sent by the Service depending on the HTTP method of the request and the syntax of the URL depending on the type. For the GET requests, the syntax can vary a lot and is explained in the following section.

RESTful Web service: HTTP methods and their equivalent VQL statements
VQL Statement HTTP Method Syntax of the Request URL
SELECT GET http://localhost:9090/denodo-restfulws/
INSERT POST http://localhost:9090/denodo-restfulws/<database name>/views/<view name>
UPDATE PUT http://localhost:9090/denodo-restfulws/<database name>/views/<view name>/<primary key value>
DELETE DELETE http://localhost:9090/denodo-restfulws/<database>/views/<view name>/<primary key value>