Skip to end of metadata
Go to start of metadata

With help of DDL Metadata variety of metadata can be defined on VDB schema models. This metadata is not limited to just defining the tables, procedures and functions. The capabilities of source systems or any extensions to metadata can also be defined on the schema objects using the OPTIONS clause. One such extension properties that Teiid defines is to expose Teiid procedures as REST based services.

Expose Teiid Procedure as Rest Service

One can define below REST based properties on a Teiid virtual procedure, and when the VDB is deployed the Teiid VDB deployer will analyse the metadata and deploy a REST service automatically. When the VDB un-deployed the REST service also undeployed.

Property Name Description Is Required Allowed Values
METHOD HTTP Method to use Yes GET | POST| PUT | DELETE
URI URI of procedure Yes ex:/procedure
PRODUCES Type of content produced by the service no xml | json | plain | any text
CHARSET When procedure returns Blob, and content type text based, this character set to used to convert the data no US-ASCII | UTF-8

The above properties must be defined with NAMESPACE 'http://teiid.org/rest' on the metadata. Here is an example VDB that defines the REST based service.

Example VDB with REST based metadata properties
<property name="{http://teiid.org/rest}auto-generate" value="true"/>, can be used to control the generation of the REST based WAR based on the VDB. This property along with at least one procedure with REST based extension metadata is required to generate a REST WAR file. Also, the procedure needs to return result set with single column of either XML, Clob, Blob or String. When PRODUCES property is not defined, this property is derived from the result column that is projected out.

when the above VDB is deployed in the JBoss AS + Teiid server, and if the VDB is valid and after the metadata is loaded then a REST war generated automatically and deployed into the local JBoss AS server. The REST VDB is deployed with "{vdb-name}_{vdb-version}" context. The model name is prepended to uri of the service call. For example the procedure in above example can be accessed as

where "sample_1" is context, "view" is model name, "g1" is URI, and 123 is parameter {p1} from URI. If you defined a procedure that returns a XML content, then REST service call should be called with "accepts" HTTP header of "application/xml". Also, if you defined a procedure that returns a JSON content and PRODUCES property is defined "json" then HTTP client call should include the "accepts" header of "application/json". In the situations where "accepts" header is missing, and only one procedure is defined with unique path, that procedure will be invoked. If there are multiple procedures with same URI path, for example one generating XML and another generating JSON content then "accepts" header directs the REST engine as to which procedure should be invoked to get the results. A wrong "accepts" header will result in error.

Make sure that the number of parameters defined on the URI must match to the parameters defined on procedure definition. An error with parameter definition will result in procedure being skipped from generation of REST based service or error with 'GET' based methods. 'POST' methods do not need to be defined with URI paths, the procedure parameters are automatically added as @FormParam annotations on the generated procedure.

Security on Generated Services

By default all the generated Rest based services are secured using "HTTPBasic" with security domain "teiid-security" and with security role "rest". However, these properties can be customized by defining the then in vdb.xml file.

Example vdb.xml file security specification
  • security-type - defines the security type. allowed values are "HttpBasic" or "none". If omitted will default to "HttpBasic"
  • security-domain - defines JAAS security domain to be used with HttpBasic. If omitted will default to "teiid-security"
  • security-role - security role that HttpBasic will use to authorize the users. If omitted the value will default to "rest"
  • passthough-auth - when defined the pass-through-authentication is used to login in to Teiid. When this is set to "true", make sure that the "embedded" transport configuration in "standalone-teiid.xml" has defined a security-domain that can be authenticated against. Failure to add the configuration change will result in authentication error. Defaults to false.
ws-security
it is our intention to provide other types of security based on ws-security in future releases.

Special Ad-Hoc Rest Services

Apart from the explicitly defined procedure based rest services, the generated jax-rs war file will also implicitly include a special rest based service under URI "/query" that can take any XML or JSON producing SQL as parameter and expose the results of that query as result of the service. This service is defined with "POST", accepting a Form Parameter named "sql". For example, after you deploy the VDB defined in above example, you can issue a HTTP POST call as

A sample HTTP Request from Java can be made like below

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Dec 05, 2013

    Important to note the case-sensitive nature of the REST URL entered to access the model in the generated war. The URL should be in all lower-case irrespective of whether the model name uses capitals or not, eg.

    A Vdb named 'RestFinancials' containing a model named 'CustomerView', using a REST GET method of 'customers' will have an URL of the form: