REST application programming

Writing your first active energy manager application using REST

Tired of waiting on the GUI to access your energy data? Want quick access to your data anywhere, even at remote locations? With some basic Java™ programming skills, and investment of your time, you can take advantage the powerful capabilities of the IBM Active Energy Manager REST APIs. This article starts with a basic understanding of REST and RESTful programming and concludes with the development of a AEM REST program for accessing and reporting power usage metrics.

Share:

Paul Sonnenberg (sonnen@us.ibm.com), Software Engineer, IBM

Paul Sonnenberg is a software test specialist with over 30 years experience testing numerous products. Recently he was responsible for the system verification test of the REST APIs for Active Energy Manager Release 4.2.



21 September 2010

Also available in Chinese

Overview

The IBM Systems Director Active Energy Manager (AEM) is a tool for monitoring and managing power and thermal usage across systems and facilities within a data center. AEM is included with IBM Systems Director editions or available as a plug-in option for IBM Systems Director. REST application programming interfaces are recent additions to both products. They are included in release 6.1.2 of IBM Systems Director and release 4.2 AEM; both were released in December 2009. This article will take you through the journey I took as product tester: from understanding the basic concepts of REST and RESTful programming, continuing with writing a simple program, and finishing with developing a moderately complex AEM application. The only assumption I make of the reader is a basic understanding of Java programming and the hypertext transfer protocol (HTTP).

Understanding REST and RESTful programming

My first task was to discover REST. After researching the web, and talking with my colleagues, I summarized it as follows: REST (Representation State Transfer) stems from a Ph.D. dissertation by Roy Fielding in 2000. In its essence, it is a type of web service. It refers to a stateless client/server architecture where the web services are viewed as resources that can be identified by their Uniform Resource Identifiers (URIs). These services are limited to the standard GET, POST, PUT, and DELETE HTTP methods. Software developed using this architecture is considered to be RESTful.

In its basic form, a REST API is a URI that can perform a single operation. For AEM, URIs are available to obtain energy metrics and to set energy management functions. For example, this URI, /IBM/director/rest/resources/PowerOutletGroup, will return a resource that contains the list of power outlet groups.

  • Resources: Objects or actions that are addressable via a URI.
  • JSON (Java Script Object Notation): The format used for all AEM resources. It is a lightweight interchange format which is easy to read and write for both humans and software.

REST APIs are programming language independent. They are accessible from any language that has a HTTP client library, including Java, Python, Perl, and so on. I chose Java mainly because I am most familiar with it. The information center for IBM Systems Director Software Development Kit (SD) is the place to start for detailed information regarding the APIs. In addition to all the detailed syntax information, it contains a samples section, which includes a number of useful Java methods. I took advantage of the REST Utilities.java class, using the methods for getting the response string and for logging.

There are numerous articles available on the web, but one that stood out for me (for both its simplicity and creativity) was written in 2004 by Ryan Tamiko entitled “How I explained REST to my wife” (see the Resources).

REST client - a simple application

Once I had a basic understanding of the REST concepts, my next task was to figure out how to put that knowledge to work in the Java programming world. What works well for me is to find a fairly simple application and build from there.

For this task I selected the REST client application from the Agile commons.org website. With a few modifications for handling the Secure Socket Layer (SSL) certification and parsing JSON formatted resources, I had a simple, straightforward Java application running in a matter of days.

One of the drawbacks to using Java in this environment, as opposed to Perl or Python, is that if you are running remotely on a system other than the one where the Systems Director server resides, you first need to import the SSL certificate into a local trust store to make secure HTTP connection using SSL. The IBM information center provides step-by-step instructions for acquiring the certificate.

The SSL modifications to REST client consisted of adding a few lines of code to input the location and password for the trusted store security certificate and the following lines to set the appropriate security properties:

Listing 1. Sample code for setting SSL security modifications
...
System.setProperty("javax.net.ssl.trustStore", certfile);
System.setProperty("javax.net.ssl.trustStorePassword", certpass);
...

Parsing JSON formatted resources requires the inclusion of JSON libraries. From the JSON.org Java website, I downloaded both the Java and HTML source files ran the following commands to create a JSON.jar library file.

javac C:/dz/json/*.java 
jar -cvf C:/$user/libs/json.jar C:/dz/json/*.class

Writing the code for parsing JSON is straightforward. The JSON libraries provide a full set of methods for parsing, selecting, and updating JSON resources, which can easily be incorporated into a general purpose application. As part of my learning curve, I added the following code segment to REST client. It simply creates a JSON object from the string data, which is the result of the GET call. Then, I output the object to see what the raw data looked like. Finally, I tested the parsing by checking to see if the object contained a cooling rate multiplier. If so, I output that value.

Listing 2. Sample code for parsing JSON Objects
try {
	JSONObject jsonResponse = new JSONObject(result); 
	System.out.println("jsonResponse " + jsonResponse);
	
	  if (jsonResponse.has("CoolingRateMultiplier")) {
	  String coolingRate = jsonResponse.getString("CoolingRateMultiplier");
	  System.out.println("");
	  System.out.println("cooling rate " + coolingRate);
	  }
	} 
   catch (JSONException e) {
	RESTUtilities.log(Level.SEVERE, logger, CLASSNAME, "main", 
	"FAIL: Exception occurred parsing JSON object.", e); }
	...

REST client is a callable from the command line on any client system that is able to connect to the Director server via the network.

For get and delete:

java -jar restclient.jar [-quiet] user pass certfile certpass GET/DELETE url

For put and post, sending the contents of a file as the body:

java -jar restclient.jar [-quiet] user pass certfile certpass PUT/POST url filename
Table 1. REST client execution options
OptionsDescription
QuietIs an optional parameter which causes only the response body to be printed, otherwise the response headers and timing information is included in the output.
UserSystems Director user ID.
PassSystems Director user password.
Cert fileFile that contains the key store certification. This file is acquired from the Systems Director server.
Cert passPassword for the certification file.
URIThe URI.
FilenameFile that contains the JSON formatted string for put or post requests.

Sample usage: Input

java -jar restclient.jar -quiet root eserve1a C:\\dz\\security\\mycerts ibmpassw0rd 
GET https://pla1098:8422/ibm/director/rest/energysettings

Sample usage: Output

jsonResponse 
{"MeteringActive":true,"MeteringInterval":5,"DefaultVoltage":220,"ThermalUnit":"CELSIUS",
"CoolingRateMultiplier":1.5,"PowerFactor":0.707,"PriceKWh":0,"PromptUser":true,
"uri":"/ibm/director/rest/energysettings","CurrencyType":"USD","PowerUnit":"WATTS",
"GUIRefreshInterval":1,"RetainDataDuration":365}

cooling rate 1.5"

In summary, this simple application performs all the basic REST services of GET, POST, PUT, and DELETE, using input from both the command line and local files. It proved to be a nice stepping stone for developing a more complex application.

Exploring the REST API using the Firefox web browser

Before discussing the next application I want to mention a handy tool that makes the job of RESTful programming a lot easier. One of the nice features of REST is that you can exploit the APIs a number of ways including through a web browser. I found using a Firefox web browser (version 3.5.8), updated with the JSONView addon proved to be a useful tool for application development (see Resources).

You bring up your Firefox web browser and enter the URI. The first time you will be prompted to enter your Systems Director user ID and password. The results are shown in the browser similar to how XML documents are shown. The resource is formatted and highlighted, and arrays and objects can be collapsed.

Figure 1. The following is a sample of the formatted JSON output from REST request for AEM supported resource groups
Sample of the formatted JSON output from REST request for AEM supported resource groups

What’s nice is that you can see the resource produced by the URI without having to write a line of code. I used it extensively when writing the next application; it saved a lot of time.

AEMpwrReport (AEM power report) application

AEMpwrReport is designed to be a more complex application, one that a customer would consider writing to extract usable data from AEM. It polls the Director server using REST APIs at regular intervals, for a specified duration, and collects input power data for all AEM monitored endpoints. Before completion, it outputs aggregate data for the individual end points, as well as summary information for all monitored endpoints. The user is able to control both the polling interval and the duration of the execution. There is also a tracing facility which allows the user the capability of seeing the result of every call that returned unique power data.

From a REST perspective, this application is pretty simple. It consists of a single innvocation of the following URI, which produces a single resource containing all the input power data for every AEM monitored endpoint.

…:8422/ibm/director/rest/groups/AEM_SUPPORTED_RESOURCES_GROUP/monitors/
[com.ibm.aem.console.base.AEMMetricProviderID][inputPower]/monitordata

The challenge is to determine when and how often to get power data. The ideal solution would be to wait on a JAMS message, or to query an indicator that indicates updated power data is available, and then perform the GET. Unfortunately, this capability is not available in the initial release of the APIs. The solution was to perform the GET at a user definable interval after each GET checks all the endpoints. Check to see if the status flag for input power is set to "Valid", and if so, then see if the time stamp has been update since the last update.

The following code shows how to parse the JSON resource and make the necessary checks:

Listing 3. Sample code for monitoring power data
|-------10--------20--------30--------40--------50--------60--------70--------80--------90
000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
...
try {  
 JSONObject jsonResponse = new JSONObject(result); 
 JSONArray jsonarr = jsonResponse.getJSONArray(MONITORDATA);
 	index = 0;
 	int length = jsonarr.length();
  	
  // for each JSON object within the array represents an AEM monitored endpoint 
 	for (int  = 0; i  < length; i++)
    {
    JSONObject aemmetric = jsonarr.getJSONObject(i);
    //"Valid" status indicates that the object contains valid 
    // or current input power data 
   	if (aemmetric.has(STATUS) & aemmetric.getString(STATUS).equals(VALID))
      { 
        ...
       pwr.timestamp.set(index,aemmetric.getString(TIMESTAMP));
       pwr.DisplayName.set(index,aemmetric.getString(DISPLAYNAME));
       
      // check to see if new input data is available. 
      // Prior_timestamp is used to store the last time new data 
      // was available.  The first time it needs to be initialized to an empty string.  
      // Check to see if the current timestamp is newer than the prior one, 
      // if it is process new data.
      if (pwr.prior_timestamp.get(index) == null) pwr.prior_timestamp.set(index,""); 
      if(pwr.timestamp.get(index).compareTo(pwr.prior_timestamp.get(index)) !=0)
        {
      	...

Usage:

Java –jar aem_pwr_report.jar [-quiet] server user pswd certfile certpswd 
duration delay tracing [tracefile]
Table 2. AEMpwrReport execution options
OptionsDescription
QuietAn optional parameter which causes only the response body to be printed, otherwise the response headers and timing information is included in the output.
UserSystems Director user ID.
PassSystems Director user password.
Cert fileFile that contains the key store certification. This file is acquired from the Systems Director server.
Cert passPassword for the certification file.
DurationThe duration of the run in hours. Minimum is 1 hour.
DelayTime in seconds between polls for new input data.
TracingTrue or false - when tracing is set to true all the input power data collected, along with time stamp data, will be saved in the designed trace file.
Trace fileOutput file for storing trace data.

Sample usage: Input

Java –jar aem_pwr_report.jar pla1079.pdl.pok.ibm.com root eserve1a 
C:\\dz\\security\\mycerts ibmpassw0rd 1 0 true C:\\dz\\aem\\4.2\\AEMpwrReport.trace

Sample usage: Outputs

  1. If the quiet flag is not specified you will get the following standard output, which by default goes to the screen:
    Power Report Application Started at: Wed Dec 09 14:38:50 EST 2009 Running for 
    1 hrs collecting data from Director Server: pla1079.pdl.pok.ibm.com 
    Monitoring 81 end points
    ******************************************************************
    
    HTTP Return Code 200
    ****** Time required to process All 81 Objects 1657 ms Average processing 
    time 1657 ms *******
    current timestamp 2009-12-09 14:38:52.453
    target timestamp 2009-12-09 15:38:50.796
    
    HTTP Return Code 200
    ****** Time required to process All 81 Objects 1265 ms Average processing 
    time 1461 ms *******
    current timestamp 2009-12-09 14:38:53.718
    target timestamp 2009-12-09 15:38:50.796
    ...

    This will continue outputting messages after each HTTP GET requested is completed, and the resultant data is processed.

    The following is a sample set of messages that are displayed after the application has completed. Note they will occur even if –quiet is specified.

    ******************************************************** 
    Completed at: Mon Dec 07 17:57:48 CST 2009
    
    The following 22 end points reported input power
    OID 4131 Name IBM MtVM 01v Q000109
    OID 4131 Total and Average Input power 16724.09/176.04 in WATTS
    OID 4131 Number of inputs 95
    
    OID 4119 Name IBM MtVM 01v Q000107
    OID 4119 Total and Average Input power 16724.09/176.04 in WATTS
    OID 4119 Number of inputs 95
    …

    Many of the monitored endpoints included in the AEM Support Group do not report input power. The following is a complete list:

    The following 59 end points reported NO input power
    OID 4539 Name Outlet Group 7
    OID 4503 Name Outlet Group 2
    OID 4560 Name Outlet Group 4
    OID 4495 Name Probe Temperature
    OID 4470 Name Outlet Group 6
    OID 4537 Name Outlet Group 6
    …

    At the bottom of the output are the aggregate totals for both input power and processing time required to acquire the data.

    Monitoring completed after 1 hrs starting at 2009-12-09 15:10:38.687 finishing 
    at 2009-12-09 16:10:41.203
    Summary: Total number of end points monitored 81 Total pwr consumed 80886.13 
    Total processing time (ms) 3601999
  2. Trace output:

    Trace output contains dash delimited records. A record is created each time an endpoint reports new input power data.

    ---------------------------------
    OID 4590 Name IBM 7978 AC1 KQFTXMD
    metric number 1
    time stamp 2009-12-09 15:03:49.0
    Input Power Value 222.75599670410156
    Cumulative Power 222.75599670410156
    ----------------------------------
    OID 4590 Name IBM 7978 AC1 KQFTXMD
    metric number 2
    time stamp 2009-12-09 15:08:51.0
    Input Power Value 222.7830047607422
    Cumulative Power 445.53900146484375
    …

As you can see AEMpwrReport is able to report power usage statistics for all managed endpoints. Also, the key thing to note is the time required for acquiring that data. You can see that I was able to acquire and process the data for 81 endpoints in a matter of seconds! Let's see you do that with the GUI. Note that this time will vary based upon both the processing capability of the Systems Director server and the networking bandwidth available between the Systems Director server and client where AEMpwrReport is running.

Summary

In summary, learning the basics of RESTful programming does take a little time and effort even with a programming background. From start to finish, it took me a nearly a month before I felt proficient with both RESTful programming and the AEM REST APIs. However, once you have taken the time to master it, you can get the data you want, how you want it, and most importantly, when you want it.


Download

DescriptionNameSize
Zip fileAEM_rest_java_code.zip16KB

Resources

Learn

Get products and technologies

  • Evaluate IBM products in the way that suits you best: Download a product trial, try a product online, use a product in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.

Discuss

  • Get involved in the My developerWorks community. Connect with other developerWorks users while exploring the blogs, forums, groups, and wikis.

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 AIX and Unix on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=AIX and UNIX, Java technology
ArticleID=524953
ArticleTitle=REST application programming
publish-date=09212010