Developing a Web 2.0 application using the InfoSphere Business Glossary REST API

IBM InfoSphere Business Glossary enables users to create, manage, and share an enterprise vocabulary and classification system. In version 8.1.1, the Business Glossary team introduced a REST API that makes glossary content easier to consume by enabling the development of custom applications based on particular needs.

This article provides step-by-step instructions on how to develop a portable, dynamic read-write widget that uses the IBM InfoSphere Business Glossary REST API in conjunction with various Web 2.0 technologies. The widget enables users to find terms, examine the term's details, and make basic edits.

Our goal is for InfoSphere Business Glossary customers to use the knowledge gained through building this sample widget as inspiration for using the REST API to create their own custom applications. This article is intended for software engineers who are familiar with Web 2.0 technologies and product designers who can apply the tools provided here to real world situations. [20 Jan 2010: Added instructional download and updated first resource. --Ed]


Gabi Nativ (, Software Developer, IBM  

Gabi Nativ is a software developer who works on the IBM InfoSphere Business Glossary team at the IBM Israel Software Lab. Gabi holds a B.Sc in Computer Science from Hebrew University of Jerusalem and has more then five years experience in the field of software development. He has been involved in Web application development for more than two years. His main interests are Java and Web 2.0 technologies.

Michael Fankhauser (, Functional Architect, IBM  

Michael Fankhauser is the Business Glossary functional and user experience architect at the IBM Israel Software Lab. Michael joined IBM as part of the Unicorn Solutions acquisition in 2006. He holds a BA in Psychology from the University of Wisconsin-Madison.

20 January 2011 (First published 10 September 2009)

Also available in Russian


This article is intended for developers who have a basic understanding of Web programming technologies (HTML, JavaScript, Ajax, XML, XSLT) and experience developing widgets with the Dojo JavaScript toolkit. To deploy the sample widget, you will need basic administration skills and permissions necessary for deploying Web application WARs on IBM WebSphere® Application Server. The Business Glossary REST API is a supported part of the IBM InfoSphere product. The other client-side components that you develop following the steps in this article are based on common Web programming technologies but are not officially supported as part of an IBM product.


IBM InfoSphere Business Glossary enables you to create, manage, and share an enterprise vocabulary and classification system. Business Glossary exposes rich functionality through an API that uses a REST (Representational State Transfer) based service. REST is an open architectural style for designing Web services that allows developers with a basic understanding of Web 2.0 technologies to quickly build applications.

This article provides step-by-step instructions on how to build a REST-based component that you can embed in any Web page. The sample component is called the BGTerm Finder widget. It is a light-weight tool that enables quick discovery and modification of a company's business vocabulary.

Following are two sample business scenarios that demonstrate how the component might be used:

  • Tom, a subject matter expert, is reviewing his company's business glossary and is surprised to see that the definition of the term Actual Net Present Value is not accurate. He immediately uses the BGTerm Finder widget to look up the term and edit it in real time to correct its definition.
  • Lorraine, a sales executive, is reading a business intelligence report when she comes across the phrase Actual Net Present Value. She needs to understand how this term is specifically defined in her company. She uses the BGTerm Finder widget to look up the term and study its context and definition.

Figure 1 shows two screenshots of the BGTerm Finder widget. The first screenshot shows that a user has searched on the string "act" and opened up the detail view for the term Actual Net Present Value. The second screenshot shows that the user has clicked on the icon for editing the term.

Figure 1. BGTermFinder Widget screenshots
Screenshots of BGTerm Finder widget. First depicts search. Second depicts edit.


The Business Glossary REST API allows client applications to access and author business glossary content. REST was the technology chosen for the API because of several advantages it offers over other distributed technologies. Most importantly, it is lightweight and interoperable.

The API exposes glossary content as resources. These resources are addressed by using URIs and are represented by XML documents that are defined by XML schemas residing on the server.

API resources

The resources that can be received by the Business Glossary REST API are divided in two major sets:

  • Entity Resource Set — This resource set contains detailed information about Business Glossary entities such as categories, terms, stewards, custom attributes, and additional assets. All of these entities are supported by the Read API. Categories, terms, and custom attribute are also supported by the Write API and its create, update, and delete capabilities. See the REST API documentation for more information.
  • Operational Resource Set — This resource set provides easy-to-use, generic operations for developing client applications, such as:
    • Autocomplete. Completion suggestions from the glossary, given a prefix (wildcards are supported).
    • Anywhere Search. Search algorithm similar to that used in IBM InfoSphere Business Glossary Anywhere (wildcards are not supported).
    • Search. This operation enables a search of the glossary for a specific pattern. The user can control the searched features and classes and the ranking of the results (wildcards are supported).

API transactions

API transactions consist of an HTTP request and response. Different operations require different kinds of HTTP methods in the request. A combination of URI and HTTP method defines what operation will occur. The REST interface provides the following HTTP methods:

  • POST — create a resource
  • GET — read a resource
  • PUT — update a resource
  • DELETE — delete a resource

Widget design

The sample BGTerm Finder widget follows the Model-View-Controller (MVC) architectural pattern for Web applications. Following is an overview of each layer and its associated technologies:

  • Model (XML) — Well defined API XML resources represent the data models.
  • View (HTML+CSS) — The widget's HTML provides structure while CSS handles styling.
  • Controller (JavaScript) — The widget's JavaScript code does the following:
    • Handles user events
    • Passes resources to and from the REST API using AJAX
    • Transforms XML resources into HTML fragments using XSL transformation
    • Injects those fragments into the DOM
    • Manipulates the user interface
Figure 2. Widget design
Depiction of the interactions among the widget components and between the widget's REST API Client and the REST API.

Model (XML)

Widget models are the XML resources that are returned by the REST API. These resources are XML documents defined by XML schemas residing on the server along with the REST API. The sample widget uses the searchResource and termResource resources.

Listing 1. Search resource model XML
<?xml version="1.0" encoding="UTF-8"?>
<searchResource xmlns="" 
			<glossaryObject class="term">
				<name>Satisfaction Rating Date</name>
				<field name="name" value="Satisfaction Rating Date"/>
Listing 2. Term resource model XML
 <?xml version="1.0" encoding="UTF-8"?>
<termResource xmlns="" .»
xmlns:xsi="" »
 xsi:schemaLocation=" .»
		<name>Satisfaction Rating Date</name>
		<createdOn>2009-05-04 04:01:59 PDT</createdOn>
		<modifiedOn>2009-07-08 07:28:42 PDT</modifiedOn>
		<shortDescription>The date on which the modern Satisfaction Rating was .»
assigned to the Customer.</shortDescription>
		<longDescription>The date on which the Satisfaction Rating was assigned.»
to the Customer.</longDescription>
		<steward class="user">
			<name>Jeff Blight Jeff Blight</name>
			<id>Jeff B</id>


The XML models described in the previous section are transformed into HTML fragments and injected into the widget DOM.

Because we are developing a widget that can be embedded in any Web page, we want to save browser resources and avoid conflicts with the containing document. Following are examples of how the HTML and CSS code accomplishes this:

  • Takes advantage of Dojo attach points and attach events, instead of IDs, to ease fragment injection
  • Uses unique CSS class names with a specific prefix
  • Uses the Dojo JavaScript toolkit to minimize the HTML footprint
Listing 3. Widget HTML template
<div class="bgTermFinderWidget_main"
	dojoAttachEvent="onclick : clickHandler">
<h1>InfoSphere <a dojoAttachPoint="bg_link" href="#"
	target="_blank" title="Go To Business Glossary Browser">Business
Glossary</a> : Term Finder <img class="bgTermFinderWidget_logo"
	src="${imagesPath}/ibm_logo_white.gif" /></h1>
<div class="bgTermFinderWidget_ds">
<div class="bgTermFinderWidget_search">
<div class="bgTermFinderWidget_tempText" dojoAttachPoint="tempText"
	dojoAttachEvent="onclick: trySetFocus">Start typing to search...</div>
<input type="text" dojoAttachPoint="searchinput"
	dojoAttachEvent="onblur:stopTimer,onfocus:startTimer" value="" /> <img
	class="bgTermFinderWidget_searchloader" dojoAttachPoint="searchloader"
	src="${imagesPath}/loading.gif" style="display: none" /></div>
<div class="bgTermFinderWidget_resultsPanel">

<div class="bgTermFinderWidget_infoHolder" dojoAttachPoint="infoHolder">
<span class="bgTermFinderWidget_info" dojoAttachPoint="info"></span></div>

<div class="bgTermFinderWidget_searchResults"
<div class="bgTermFinderWidget_showmore" /></div>


<div class="bgTermFinderWidget_itemloaderholder"
	class="bgTermFinderWidget_itemloader" dojoAttachPoint="itemloader"
	title="Status Indicator | Click to reload widget" /></div>


The main div in the widget HTML structure is the SearchResults div. This div is responsible for displaying terms in response to the user's typed input.

The results are received in the SearchResult Model XML format, transformed into HTML fragments, and appended to the SearchResults div.

The HTML search result fragments are div tags uniquely identified by the same Repository ID (RID) used by Business Glossary. The controller uses this RID to get the full term resource when requested by the user. An additional custom HTML attribute that identifies the steward of a resource is also used.

Listing 4. Search results HTML
<div dojoattachpoint="searchResults"
<div class="page">
<div class="node"
<div class="title-closed"><a class="doOpen" href="#">Satisfaction
Rating Date</a><a class="doEdit" href="#"
	title="Click to edit Description and Steward">Edit</a></div>
<div class="node"
<div class="title-closed"><a class="doOpen" href="#">Source Of
Income Type Identifier</a><a class="doEdit" href="#"
	title="Click to edit Description and Steward">Edit</a></div>
<div class="node"
<div class="title-closed"><a class="doOpen" href="#">Special
Terms Flag</a><a class="doEdit" href="#"
	title="Click to edit Description and Steward">Edit</a></div>
<div class="bgTermFinderWidget_showmore" /></div>

Result nodes

A result node can have one of the following states:

  • Closed
  • Open for viewing
  • Open for editing

Each state has a different presentation, which is controlled by CSS. The following three figures show an example of each state.

Figure 6. Closed — Displaying only term name
Example term Satisfaction Rating Date shown preceded by a twistie icon pointing to the right to indicate that details are available, but not shown
Figure 7. Open for viewing — Displaying term details and edit icon
Example term with edit icon, description, and steward name. The twistie icon now points down to indicate the term is open.
Figure 8. Open for editing – Displaying term details and steward in edit mode with edit controls
Description is now in a editable text field, steward name is in a menu select control, and there are buttons labeled Ok and Cancel.

Controller (widget JavaScript code)

The central piece of the widget is the controller. The controller consists of JavaScript code that reacts to user actions by calling the REST API. Then through the use of DOM manipulation, the controller injects transformed HTML fragments into the widget template.

DOM manipulation and bubbling technique

In order to understand the logic of the DOM manipulation performed by the controller, this section provides an in depth look at the Open Node scenario. The Edit Node scenario follows similar logic.

Figure 9. Sequence flow — open node
Click initiates a chain of events between the widget and REST API that results in an HTML fragment being injected into the HTML DOM

When a user clicks on a closed node, the onClick event of the target node is bubbled up by the browser to the main onClick handler of the widget's controller code. The main handler uses the RID to identify the target node and calls the appropriate handler method.

The event bubbling technique provides the ability to disconnect the view structure of the widget from the controller code. The technique also follows the single choice principle of concentrating all the onClick handling in one place.

Listing 5. Click handler function
clickHandler : function(evt) {
		var targetNode =;
		var className  = dojo.attr(targetNode,"class");		
		if ( className == "doOpen") {
			var div  = targetNode.parentNode.parentNode;
			this.OnItemClick( div );

		else if ( className == "doEdit") {
			var div  = targetNode.parentNode.parentNode;
			this.OnItemEditClick( div );
		else if ( className == "editOK"){
			var div  = targetNode.parentNode.parentNode.parentNode;
			this.OnEditOk (div);
		else if ( className == "editCancel"){
			var div  = targetNode.parentNode.parentNode.parentNode;
			this.OnEditOk (div);
		else if ( className == "doShowMore"  ) {
			this.OnPageClick( dojo.attr( targetNode,"page") );

//Method is called when user clicked to open/close the node
OnItemClick:function( div){	
		this._currRID  = dojo.attr(div,"rid");
		var nodesClosedTitle = dojo.query('.title-closed' , div);
		var nodesClosedBody = dojo.query('.body-closed' , div);
		//Node is closed and never been open				
		if ( nodesClosedTitle.length > 0 &&  nodesClosedBody.length == 0){

			//Performing Ajax call to term details
			this.RequestItemDetails( this._currRID );
          //Node is closed and was opened before
		else if ( nodesClosedTitle.length > 0 && nodesClosedBody.length > 0){
			nodesClosedTitle[0].className = "title-open";
			nodesClosedBody[0].className = "body-open";
          //Node is open 

			var nodesOpenTitle = dojo.query('.title-open' , div);
			var nodesOpenBody = dojo.query('.body-open' , div);
			if ( nodesOpenTitle.length > 0 && nodesOpenBody.length > 0){
				nodesOpenTitle[0].className =  "title-closed";
				nodesOpenBody[0].className = "body-closed";	

As shown in Listing 6, if the node was never opened, the controller asynchronously requests the term details by calling RestClient.requestItemDetails.

Listing 6. RequestItemDetails function
//Performing AJAX Request to term details
RequestItemDetails:function( rid ){
 	( rid,this,this.itemDetailsCallback , this.onError );

In the code in Listing 7, the callback method of the controller first generates the HTML fragment using the XSLProcessor module and then injects it into the targeted node.

Listing 7. itemDetailsEditCallback function
//Method will be called when AJAX request to term details returns .
itemDetailsEditCallback :function( xml ) {

	//Extracting the rid of the term with XPath
	var rid = this.extractStringValue »
( xml ,"//rest:termResource/rest:term/rest:uri" );

	var div = dojo.query('div[rid=\"'+ rid +'\"]' , this.searchResults )[0];

	//Processing XML of term details to create HTML edit  fragment to be injected.�
	var element = this._bgXslProcessor.processItemDetailsEdit( xml );

	//Switching display 
	dojo.query('.doEditBussy' , div)[0].className = "doEdit";
	dojo.query('.title-open' ,div )[0].className = "title-edit";

	//Injecting the HTML fragment element , dojo.query('.body-open' ,div )[0] , "replace"); this._selectTag ,dojo.query('.stewardValue' ,div )[0],"only" );


REST client module

The widget uses a Dojo JavaScript class (BGRestClient) to perform asynchronous REST calls for specified resources.

Listing 8 shows the two main helper functions that perform the AJAX GET and PUT asynchronous calls.

Listing 8. REST client code snippet
	//Performing AJAX Get Request
	__performRequest: function( url , callbackMethod , errorMethod ) {
		if ( this._xhr != null ) {
		this._xhr =  dojo.xhrGet( { // 
			// The following URL must match that used to test the server.
			url: url, 			
			handleAs: "xml",
			timeout: this._timeout, // Time in milliseconds
			// The LOAD function will be called on a successful response.
			load: callbackMethod,
			// The ERROR function will be called in an error case.
			error: errorMethod 

	//Performing AJAX Put Request 
	__performPutRequest: function ( url , data , callbackMethod , errorMethod ) {
		return dojo.rawXhrPut( { // 
			// The following URL must match that used to test the server.
			url: url, 
			handleAs: "xml",
			putData : data ,
			timeout: this._timeout, // Time in milliseconds
			// The LOAD function will be called on a successful response.
			load: callbackMethod,
			// The ERROR function will be called in an error case.
			error: errorMethod 

See the BGRestClient.js file contained in bgTermFinderWidget.war to see the implementation of the JavaScript REST client.

XSLProcessor Module

The XSLProcessor acts as a cross-browser wrapper to transform XML resources received from the API into HTML fragments.

The main XSLProcessor transformation function uses the browser's XSL transformation engine to process the XML.

Listing 9. XSLProcessor code snippet
__transform:function( xml , xsl ,paramsNames,paramsValues) {
	var element = null;
	if (dojo.isIE)
		var template = new ActiveXObject("MSXML2.XSLTemplate");
		template.stylesheet =  xsl;			
		var processor = template.createProcessor();
		processor.input = xml;
		if (paramsNames != null  ) {
			for( i = 0 ;i < paramsNames.length ; i++){
		element =  processor.output;
	else if (dojo.isFF || dojo.isChrome)
		xsltProcessor=new XSLTProcessor();

		var i = 0;
		if ( paramsNames != null ) {
			for( i = 0 ;i < paramsNames.length ; i++){
,paramsValues[i] );

		//Performing the transformation of a fragment of xml
		element = xsltProcessor.transformToFragment( xml , document)
	return element;


Internet Explorer XSL processor

Internet Explorer uses the Microsoft.XMLDOM.transformNode method to process an XML node and its descendants with a specified XSL document. The method returns the result as a plain text version of the transformed node.

Firefox XSL processor

Firefox performs the transformation by creating an instance of the XSLTProcessor, importing the XSL document, and using the xsltProcessor.transformToFragment method to perform the transformation. The returned result is a DOMNode.


As stated earlier, this article assumes you are already familiar with XSLT development, however, please note that Business Glossary REST API XML resources are all declared with the following designated XML namespace:

This namespace must be taken into account when developing XSLT. See Listing 10 for an example.

Listing 10. REST API namespace
<xsl:stylesheet version="1.0"xmlns:xsl="" 
        xmlns:rest="" >

Listing 11 shows an example of how to use the declared rest prefix.

Listing 11. Using the declared "rest" prefix
<div class="description">
<xsl:value-of select="rest:termResource/rest:term/rest:shortDescription"/>

All the XSL files used by the widget are contained in the bgTermFinderWidget.war file in the js/bg/resources/xsl directory.


Use the following steps to deploy the widget:

  1. Go to the Download section and save the bgTermFinderWidget.war file.
  2. Use the WebSphere Application Server Web Administrative Console to deploy the WAR file. You must deploy onto the same host that your Business Glossary REST API is on, or onto a sub-domain host. This deployment requirement is due to the same origin policy that is implemented in all major browsers. The policy prevents script loaded from one site origin to perform AJAX calls to another site with a different origin.
  3. Go to the deployed WAR and modify the RestAPIHost attribute in the Main.html file to match the name of your host.
  4. To work with the widget, open a browser and go to:

    The widget supports the following browsers:

    • Internet Explorer versions 6, 7, and 8
    • Firefox versions 2 and 3
    • Google Chrome


Following are examples of the BGTerm Finder widget integrated in third party environments.

Figure 10. Lotus Mashup integration
Screenshot of a Lotus Mashup environment that includes the BGTerm Finder widget.

As shown above, we are able to use the iWidget standard to wire our sample widget to another widget within the Lotus Mashup framework.

Figure 11. iGoogle
Screenshot of an iGoogle page that includes the BGTerm Finder widget.
Figure 12. Netvibes
Screenshot of a Netvibes page that includes the BGTerm Finder widget.


The IBM InfoSphere Business Glossary 8.1.1 REST API provides you an unprecedented ability to expose glossary content to your users through your own custom applications. We hope that the examples provided to you in this article will enable you and your organization to begin leveraging the power of InfoSphere Business Glossary through the REST API.


The authors would like to thank Ilan Prager, Joshua Fox, and Erel Sharf for their feedback and review of this article.


BGTermFinderWidget code samplebgTermFinderWidget.war9.73MB
Instructions for deploying BGTermFinderWidgetbgTermFinderWidget-deployment.doc1.33MB


  • Obtain the InfoSphere Business Glossary REST API reference documentation by installing IBM InfoSphere Business Glossary and including the documentation as an installation option. The documentation is a subset of the installed IBM InfoSphere Information Server information center under the InfoSphere Business Glossary > Developing and extending applications section. More InfoSphere Business Glossary information is available from the online IBM InfoSphere Business Glossary information center.
  • W3Schools provides online reference information for many Web technologies such as JavaScript, CSS, HTML, DOM, XML, etc.
  • For more in-depth information on Web technologies refer to the developerWorks Web development zone and the developerWorks XML zone.
  • Use the Dojo toolkit documentation pages for more information about the Dojo JavaScript toolkit.


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Information management on developerWorks

Zone=Information Management, Web development
ArticleTitle=Developing a Web 2.0 application using the InfoSphere Business Glossary REST API