Loading ...

OpenWGA 7.10 - OpenWGA Concepts and Features

Design and development » REST web service » The REST APIs

The Query API

The query API complements HDBModel and CMS API by providing a way to define custom queries whose results are retrievable via REST.

The query API itself normally does not return any real document data. Instead it returns links to the query result documents which point to their representation on the HDBModel or CMS API (depending if it is HDBModel data or not).  So to resolve those links on a REST client at least one of these APIs needs to be enabled too.

An alternative is to enhance the query result collection to include the necessary data directly on the query result. See the chapter "Enhancing query results" on this document for details.

The available queries are predefined in form of TMLScript objects. To define a query:

  • Create a new script module in your design under folder /scripts/tmlscript/wga/rest/queries. The name of the module file will be the name of the query.
  • The contents of the script module will be used as a custom TMLScript object. You need to create a method query(). It currently receives no parameters but you can access the request in it via WGA.request where you could read URL parameters that are passed to the query.

This method should execute some query functionality - maybe a "real" OpenWGA database query, maybe something completely different - and then return an object of one of the following types which should contain the queries result documents:

See this example which executes a database query and receives a URL Parameter "gps" which directly goes into a query parameter: 

this.query = function() {
  var params = {gps: request.getParameter("gps") == "true" ? 1 : 0};
  return WGA.app().query("hql", "... hql query ...", null, params);
}

You can then call this query via URL:

/rest/v1/query/{queryName}

The result will be formatted like a document collection from CMS or HDBModel API, providing the data of the contained documents. For example:

{

}

The URIs of the results point to content document either inside the HDBModel API (if the app is a HDBModel-enabled app) or the CMS (if not). So you need to keep one of both enabled in order to resolve resources provided by the query API.

Enhancing query results

Just as any collection the query results can also be enhanced with additional data. Chapter Working with documents in REST describes how this can be done using custom enhancers which are requested via URL parameter.

If you want your query to add some data to the result independently of any URL parameter you can also create a method "enhance" for your query API object. It works just like normal custom enhancers. It will get called for every result document, receives a RESTEntry object as parameter and can use this to add items, metadata fields or relations to the REST response.

See the following example of a simple query which also defines an enhancer, adding some items to the output of each document:

this.query = function() {
  return WGA.dataSource("customjdbc").query("hql", "select * from users");
}

this.enhance = function(ref) {
  ref.addItem("firstName", firstName);
  ref.addItem("lastName", lastName);
  ref.addItem("id", id);
}

The "enhance" method on query API objects is supported since OpenWGA 6.3.3