Develop an iOS application with the InfoSphere Business Glossary REST API

InfoSphere® Business Glossary enables you to create, manage, and share an enterprise vocabulary and classification system. InfoSphere Business Glossary includes a REST API that makes glossary content easier to consume by enabling the development of custom applications. In this article, step-by-step instructions show how to develop a dynamic iOS application using the InfoSphere Business Glossary REST API. The application lets users find business glossary assets, examine the asset's details, and contact the steward using the native phone and email applications on the iOS device. After building the sample application, you'll be on your way to using the REST API to create your own custom applications with InfoSphere Business Glossary.

Benny Halberstadt (bennyhal@il.ibm.com), Senior Architect, IBM

Author PhotoBenny Halberstadt is a Senior Architect for IBM InfoSphere Governance Tools. He has worked on InfoSphere Information Server and InfoSphere Business Glossary products for the past seven years. He has extensive development experience for IBM and other companies.



Nancy Navarro (nancyn@il.ibm.com), Information Developer, IBM

Nancy NavarroNancy Navarro is an advisory information developer for IBM who has worked on InfoSphere Information Server and InfoSphere Business Glossary products for the past five years. She has extensive information development experience for IBM and other companies.



07 August 2014

Overview

With InfoSphere Business Glossary, you can create, manage, and share an enterprise vocabulary and classification system. InfoSphere Business Glossary exposes rich functions through an API that uses a Representational State Transfer (REST)-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 for building an iOS application that uses the InfoSphere Business Glossary REST API to deliver an enterprise vocabulary to the iOS environment. The sample application is a lightweight application that enables quick discovery and modification of a company's business vocabulary. The vocabulary is not stored on the iOS device; instead, the REST API is used dynamically to access the glossary content on demand.

InfoSphere Information Server is an integrated set of components that includes InfoSphere Business Glossary, InfoSphere DataStage®, InfoSphere FastTrack, InfoSphere Information Analyzer, InfoSphere Information Services Director, InfoSphere Metadata Workbench, and InfoSphere QualityStage®.

The InfoSphere Business Glossary REST API is a supported part of the InfoSphere Information Server. The iOS application that you can develop by following the steps in this article is based on the REST API and the iOS operating system, but is not officially supported as part of an IBM product. The sample application was written using InfoSphere Business Glossary 9.1 and iOS 7.1.

You can download an executable of the sample program, InfoSphere Business Glossary Client Sample Application for iOS, from the Apple App Store (see Resources).

Prerequisites

This article assumes a basic understanding of XML, REST, and iOS. To deploy the sample application, you need access to a device that runs iOS. See Resources for more information about developing iOS applications.


Scenarios

The following sample scenarios describe how you might use a mobile InfoSphere Business Glossary application:

  • Lorraine, a sales executive on the way to a client, receives a business email that contains the phrase "Account Accruement." She is not familiar with this term and needs to understand how it is specifically defined in her company. She uses the InfoSphere Business Glossary iOS application to look up the term and study its context and definition.
  • Tom, a subject-matter expert, is reviewing his company's business glossary on his iOS device while waiting in the airport for his flight. He is surprised to see that the definition of the term "Accounting Period" is not accurate. He edits the term in real time to correct its definition.

The sample application described in this article supports the first scenario.

Figure 1 shows the sample iOS application. A user opened the details view for the term "Account Accruement." The view shows the definition of the term, the labels associated with it, its steward or person responsible, and parent category. All of the term's attributes can be accessed by the other sections (General Information and Modification Details). Next to the steward's name are icons enabling the user to call, send an email, or text the steward directly.

Figure 1. InfoSphere Business Glossary Client Sample Application for iOS
Image shows InfoSphere Business Glossary Client Sample Application for iOS

The InfoSphere Business Glossary REST API

The InfoSphere Business Glossary REST API allows client applications to read and write business glossary content. REST was chosen for the API because it offers several advantages over other distributed technologies. Most importantly, it is lightweight and interoperable. The API exposes glossary content as resources. These resources are addressed by using uniform resource identifiers (URIs). The URIs 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 InfoSphere Business Glossary REST API are divided into the following two major sets:

Entity resource set
Contains detailed information about InfoSphere Business Glossary entities, such as categories, terms, stewards, custom attributes, and additional assets. All are supported by the Read API. Categories, terms, and custom attributes are also supported by the Write API and its create, update, and delete capabilities.
Operational resource set
Provides easy-to-use, generic operations for developing client applications, such as:
  • Auto-complete — Provides completion suggestions based on terms in the glossary, given a prefix
  • Anywhere Search — Similar algorithm to that used in InfoSphere Business Glossary Anywhere
  • Search — Enables a search of the glossary for a specific pattern; user can control searched features and classes and the ranking of the results

The InfoSphere Business Glossary REST API documentation contains full descriptions of the resource sets (see Resources).

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 methods defines what operation will occur. The REST interface provides the following HTTP methods:

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

Invoking REST from iOS

There are many ways to invoke a REST service from an iOS application. Invoking a REST service is no different from submitting any other type of web request. The iOS code needs the connection details to InfoSphere Business Glossary on the server. The connection details are obtained from the settings the user enters into the iOS device. Using these details, the REST URI is submitted to InfoSphere Business Glossary. InfoSphere Business Glossary then returns an XML document that represents the REST resource to the iOS code. The steps for exchanging the information are standard and they are readily available online.

The XML document needs to be parsed by the iOS application. The sample application uses an XML parser developed by Google as part of its Objective-C client library. Consisting of just an M file and a header, it supports reading and writing XML documents and XPath queries. See Resources for a tutorial on how to use this library.

Listing 1 shows how the Google XML parser is used to parse a REST resource that represents a term.

Listing 1. Using Google XML parser to parse a REST resource
+ (id) loadTermXML:(NSData *)xmlData  {
  NSError *error;
  GDataXMLDocument *doc = [[GDataXMLDocument alloc] initWithData:xmlData
    options:0 error:&error];

  GDataXMLElement *termElement = (GDataXMLElement *)
    [[doc.rootElement elementsForName:@"term"] objectAtIndex:0];

  NSString *termName = [self getSingleInfo:termElement name:@"name"];
  NSString *termUri = [self getSingleInfo:termElement name:@"uri"];

  NSArray *subElements = [termElement children];
  for (GDataXMLElement *subElement in subElements) {

	if ([subElement childCount] == 1) {
	  GDataXMLElement *singleElement = (GDataXMLElement *)
	    [subElement childAtIndex:0];
	  if([singleElement childCount] == 0) {
	   NSString *key = [subElement name];
	   NSString *val = singleElement.stringValue;
	   //add the key value to the display of the term...
	  }
        }
   }
}

After the XML document is parsed, the created objects are used to display the REST resource to the user using the Details controller.

Building an InfoSphere Business Glossary REST URI in iOS

InfoSphere Business Glossary references each of its assets using a repository identifier (RID), which is a unique string that is generated by the metadata repository. The RID of an asset does not change over time, so it is a safe way to reference or identify an asset. For this reason, the InfoSphere Business Glossary REST API uses RIDs in the URI of an asset. Listing 2 shows how to create a valid InfoSphere Business Glossary REST URI.

Listing 2. Creating a valid InfoSphere Business Glossary REST URI
typedef enum {
    Term,
    BusCategory,
    Rule,
    Policy
} AssetType;

+ (NSString*) getAssetUrl:(AssetType)type rid:(NSString*)rid {
    switch (type) {
        case Term:
            return [NSString stringWithFormat:@"bgrestapi/v4/term/%@", rid];
            break;
        case BusCategory:
            return [NSString stringWithFormat:@"bgrestapi/v4/category/%@",
rid];
            break;
        case Rule:
            return [NSString stringWithFormat:@"bgrestapi/v4/rule/%@", rid];
            break;
        case Policy:
            return [NSString stringWithFormat:@"bgrestapi/v4/policy/%@",
rid];
            break;
        default:
            assert(FALSE);
            break;
    }
}

Application design

Our sample iOS application is constructed from six iOS view controllers:

  • Home
  • Settings
  • Search
  • Browse
  • Details
  • About

Home

The Home controller displays the application's initial (home) screen. Users choose the function they want to go to from this screen. Figure 2 shows an example of an InfoSphere Business Glossary with selections for text search, clipboard search, browse, and suggest term.

Figure 2. Home controller
Image shows Home controller

Settings

A Settings controller lets the user provide the connection details of the InfoSphere Business Glossary server. The first time users access the application, they must navigate from the Home screen to the Settings screen to configure the server connection information. As shown in Figure 3, connection information includes username, password, host name, and port. This information persists so the connection details only need to be set the first time the application is used.

Figure 3. Settings controller
Image shows Settings controller

Search

The Search controller lets the user search for terms. Users can use the keyboard to type a search string or use voice input.

The REST API provides three different types of search. In this sample application, the user is provided with auto-complete when typing, as in Figure 4. Regular search, without auto-complete but with wildcard support, is performed if the user taps the search button on the keyboard. An alternative approach might be to provide a user-configurable choice of search types.

Image shows Search controller

Browse

A Browse controller lets the user navigate through the glossary hierarchy, one level at a time, as shown in Figure 5. Initially, the top-level categories and information governance policies are displayed. If the user taps the name of a category or policy, the next level of the hierarchy for that category or policy is displayed. If the user taps the i icon for a category or policy, the details for the category or policy are displayed.

Figure 5. Browse controller
Image shows Browse controller

Details

A Details controller displays all of the details of a particular asset, as in Figure 6. Assets can be terms, categories, information governance policies, information governance rules, stewards, or any other asset in the InfoSphere Information Server repository assigned to a term or rule.

The controller invokes the REST API to get the details of the asset. The item's name and description are displayed prominently at the top of the page, followed by the parent category or policy, the steward, and any labels. The user can tap to open other sections with more information.

To immediately contact the steward, the user can tap one of the icons adjacent to the steward name to navigate to the native email, SMS, or phone application of the iOS device.

The controller displays references as active links to tap to see details of a related asset. For example:

  • A synonym for another term is a link that will display the details of the synonym.
  • The reference to the steward is a link that will display the details of the steward.
  • A rule that is governed by a policy is a link that will display details of the rule.

Users can navigate the glossary by using the links. For example, they can move from a term to related terms, synonyms, parent category, steward, and so on. Or, users can navigate from parent policies to sub-policies and their rules.

Although the sample application does not include editing, an application could also let the user edit the content of the page. Changes would be sent back to the InfoSphere Business Glossary server via a PUT request as an update to the item.

Figure 6. Details controller
Image shows Details controller

About

The About controller displays version and licensing information, such as in Figure 7.

Figure 7. About controller
Image shows About controller

Application flow

Figure 8 shows an example sequence in which a user could navigate through different activities of the sample application.

Figure 8. Activity flow
Image shows Application flow

On application start-up the Home screen is displayed, then the following sequence of events occurs (the numbers in Figure 8 correspond to the numbers below).

  1. The user navigates to the Settings screen. This screen lets the user set the connection details to the InfoSphere Business Glossary host server. The settings persist on the iOS device and will be used on future invocations of the application.
  2. The user navigates back to the Home screen.
  3. From the Home screen, the user taps the Text Search icon, which is represented by an image of a magnifying glass. This opens the Search screen.
  4. From the displayed keyboard the user starts typing a string to search for. Alternatively, the user could state the term aloud to use the built-in iOS voice detection. Glossary assets that match the typed string or stated term are displayed in a list. The user scrolls through the list and selects a specific glossary asset.
  5. The Details controller opens the Details screen, which displays the attributes of the selected asset.

Conclusion

The InfoSphere Business Glossary REST API lets you easily expose glossary content through custom programs, including mobile applications. The iOS example discussed in this article provides a proof of concept showing you how to bring the power of InfoSphere Business Glossary to mobile devices.


Acknowledgements

The authors would like to thank Michael Fankhauser, Evgeny Chernis, and Erel Sharf for contributions to the design of the InfoSphere Business Glossary iOS application and to this article.

Resources

Learn

Discuss

Comments

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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=979588
ArticleTitle=Develop an iOS application with the InfoSphere Business Glossary REST API
publish-date=08072014