How to test REST APIs for IBM Systems Director using Java

Automated REST API testing for IBM Systems Director

IBM Systems Director is a platform management solution that is used to manage physical and virtual systems in a multi-system environment. It supports various virtualization technologies and multiple operating systems across IBM and non-IBM platforms. This tutorial explains basic steps, tips and tricks to automate REST API testing for IBM Systems Director using Java™ code.

Share:

Piyush Jain (piyushjain@in.ibm.com), Staff Software engineer, IBM China

piyushPiyush Jain is a Staff Software Engineer at IBM currently working on VMControl under IBM Systems Director, a critical product in IBM's product portfolio. He has an overall experience of 5 years and holds a bachelor's degree in Information Technology Engineering from IET Alwar, Rajasthan India. You can contact him at piyushjain@in.ibm.com



Prashant Pareek (prashant.pareek@in.ibm.com), Staff Software engineer, IBM China

prashantPrashant Pareek is a Staff Software Engineer at IBM currently working on VMControl under IBM Systems Director, a critical product in IBM's product portfolio. He has an overall experience of 7.5 years and holds a bachelor's degree in Information Technology Engineering from VTU, Karnataka, India. You can contact him at prashant.pareek@in.ibm.com



07 May 2012

Also available in Chinese

Before you start

Learn what to expect from this tutorial, and how to get the most out of it.

About this tutorial

IBM Systems Director supports three types of interfaces: graphical user interface (GUI), command line interface (CLI) and application programming interface (API) using RESTFul webservices. This tutorial focuses on testing ISD REST APIs. REST stands for Representational State Transfer. The REST-style architectures consist of clients and servers. There is already a lot of information available on the internet for REST APIs, but this tutorial aims specifically at REST API testing for IBM System Director and provides tips and tricks for troubleshooting based on real-time hands-on experience.

Objectives

The main objective of this tutorial is to help developers and testers working on IBM Systems Director to automate the REST API testing using Java.

Prerequisites

You should have IBM Systems Director V6.x.x installed on your system before proceeding. This tutorial assumes that you are familiar with using IBM Systems Director. It also assumes that you have a reasonable understanding of REST API, Java, Eclipse IDE and JUnit.

System requirements

You should have the following components on your system:

  • Firefox Poster add-on installed on Firefox browser
  • JUnit 4.x
  • Configured IBM Systems Director
  • Eclipse

How to test REST APIs for IBM Systems Director using Java

Let's begin

About REST APIs

  1. REST stands for Representational State Transfer. REST-style architectures consist of clients and servers. IBM Systems Director also provides an interface based on RESTFul webservices. IBM Systems Director is a web-based tool and provides extensive support for REST. Almost all functionality that is supported through CLI and GUI is also supported through REST APIs. REST works on the HTTP protocol. It supports the following HTTP methods:

    • POST: This method is to create a new resource.
    • PUT: This method is to modify the existing resource.
    • GET: This method is to retrieve the information about the resource.
    • DELETE: This method is to delete the resource.
  2. Types of REST operations and return codes:

    There are two types of REST operations:

    1. Synchronous operations:

      It is a type of operation where a REST API call blocks until the job is finished. It will return with the HTTP return code and response (if applicable) after the completion of job. A few examples of return codes for this type of operations are:

      • 200: The request succeeded. All GET operations return 200.
      • 204: No content
      • 304: Nothing to change
    2. Asynchronous operations:

      It is a type of operation where the REST API call will launch a job and comes out with the return code and location, enabling the user to determine the status of the job. User can poll the location or use the JMS based listeners until the operation is completed. A few examples of return codes for this type of operations are:

      • 201 CREATED: The resource was created. All POST operation returns 201.
      • 202 ACCEPTED: The request has been accepted for processing. Some of the PUT and DELETE operation returns this code.
  3. 3. Some HTTP error codes:
    • 400 - The request was not valid. The request might be incorrect, or the data in the request is not in the correct format.
    • 401 - The request requires user authentication.
    • 404 - IBM Systems Director Server has not found anything matching the resource specified in the request URI.
    • 500 - IBM Systems Director encountered an unexpected condition which prevented it from processing the request.

Ways to test the REST APIs

  1. Manual (using a tool): Use some external REST clients like Firefox Poster, http4e etc. and invoke REST APIs manually. We have used Poster for this tutorial. You can use the REST client of your choice.
  2. Automated: To invoke the REST APIs automatically using programming language or scripts. This tutorial will cover the automated testing using Java. You can use any other language or script of your choice.

Both the approaches are explained below:

  1. Manual (using Poster):

    In this section, we will discuss manually testing some of the basic functionality of IBM Systems Director using Poster:

    1. Get the list of resources (GET Operation)
    2. Discovery of a new resource (POST Operation)
    3. Modify discovered resource (PUT Operation)
    4. Delete resource (DELETE Operation)
    1. Get the list of resources (GET Operation):

      As shown in Figure 1, you can list the resource using the GET operation. GET retrieves information about the resource. Request for retrieving resources is as shown in Figure 1

      Figure 1. GET operation using Poster
      Sample figure containing an image

      In Figure 1, you user can see the following information:

      1. URL: URI to retrieve information about Server.
      2. Actions : Selected action is GET.
      3. Header section: User needs to enter following entries in this section :
        • ISDAPIVersion: Version of the IBM Systems Director.
        • Authorization: It is a base64 converted user ID and password for IBM Systems Director.
        • Accept: Acceptable content type

      Responses are shown in Figure 2:

      Figure 2. Response of the GET operation
      Sample figure containing an image

      In Figure 2, you can see the response from IBM Systems Director for the GET request. Response contains a return code as well as the response body. Return code in Figure 2 is 200 (OK), whereas response body has the list of all the resources as returned by IBM Systems Director.

    2. Discover resources (POST operation):

      Discovery is a very basic operation of IBM Systems Director used to discover a resource. You need to use the POST method for discovery, hence you need to provide the HTTP body (JSON) along with the HTTP header. The HTTP body for discovery looks like this:

      Listing 1. Input JSON for POST discovery operation
      {
      	"IPAddress": ["9.1.2.3"],
      	"ResourceTypes": ["Server", "OperatingSystem"]
      }

      You need to provide the IP address of the resource and the resource type. A resource can be discovered using a POST operation as shown in Figure 3.

      Figure 3. POST operation to discover resource
      Sample figure containing an image

      Responses are shown in Figure 4:

      Figure 4. Response of POST operation for discovery
      Sample figure containing an image

      A few important things to note in HTTP response in Figure 4:

      • Return code: It is 201 for the POST request
      • Location: POST operation is asynchronous operation and it includes returned location. Location is a URL, which can be used to check the status of the job using GET operation as shown in Figure 1.

      Response of a GET operation using Location URI is shown in Figure 5.

      Figure 5. Response of GET operation for location URI
      Sample figure containing an image

      In HttpResponse, as shown in Figure 5, you can see following values:

      • URI: It is the "Location" of the previous POST operation.
      • Percent Complete: It shows the completion status of the task in percentage. It is 100% in Figure 5, which means that task has been completed.
      • DiscoveryStatus: This field tells the status of job, that is, whether it was successful or not. Its value is "Ok" in the Figure 5, which means the job has been completed successfully.
    3. Modify resource (PUT operation):

      To modify an existing resource, you need to use the PUT operation. For the PUT operation, you need to pass the HTTP body along with the HTTP header. The HTTP body for modify resource looks like:

      Listing 2. Listing 2. Input JSON for PUT modify resource operation
      {
      	"Properties": {"DisplayName" : "NewName"}
      }

      You can modify a resource using a PUT operation as shown in Figure 6.

      Figure 6. PUT operation to modify a resource
      Sample figure containing an image

      The response to the PUT request is shown in Figure 7:

      Figure 7. Response to PUT request
      Sample figure containing an image

      As shown in Figure 7, IBM Systems Director has returned 204 as the return code, which means it has no content to return and the request was submitted successfully.

    4. Delete resource (DELETE operation):

      The DELETE method is used when you need to delete a resource. You need to append the OID of the resource that you want to remove to the URI itself. A resource can be deleted using a DELETE operation as shown in Figure 8.

      Figure 8. DELETE operation to delete a resource.
      Sample figure containing an image

      Response of the DELETE operation is as shown in Figure 9.

      Figure 9. Response of DELETE operation
      Sample figure containing an image

      As shown in Figure 9, IBM Systems Director has returned 204 as the return code, which means it has no content to return and the DELETE request was submitted successfully.

      We have covered four basic operations of ISD REST APIs using Poster. Similarly, you can manually test or use the other IBM Systems Director functionality using this tool or some other tool of your choice. You can also automate the entire process by accessing these REST APIs programmatically. The next section of this tutorial talks about the steps required to perform all of the above mentioned IBM Systems Director REST API functionality using a Java program

  2. Automated (using Java code):

    Here also we will see the same four functionalities that we have discussed above. We have used Apache's HttpClient and HttpResponse classes to invoke the REST APIs and also to read the response. We have used these classes to simplify the process of updating the request header as well as passing the HTTP body as an argument. You can even use the HttpURLConnection class of Java or any other utility of your choice for making these calls. You can invoke the ISD REST API programmatically as follows:

    1. List resources (GET operation):

      The GET operation lists the information about the resource. For running the GET request for IBM Systems Director, we need to modify the sendGetRequest method of HttpClient for IBM Systems Director related entries as shown in Listing 3:

      Listing 3. sendGetRequest method in HttpClient.java
      		.
      		.
      		.
      sendGetRequest(String uri){
      	GetMethod method = new GetMethod(uri);
      
      	method.addRequestHeader(new Header("Accept","application/json"));
      	method.addRequestHeader(new Header("Accept-Language", "en_us"));
      	method.addRequestHeader(new Header("ISDAPIVersion","6.2.1.0"));
      	method.addRequestHeader(new Header
      				("Authorization", "Basic cm9vdDpnbzRic=="));
      
      	int statusCode = client.executeMethod(method);
      	return statusCode;
      }

      In the code snippet shown in Listing 3, you can see the following information:

      1. Initialize an object of the GetMethod class and pass the URI to it.
      2. Add the Request header to the GetMethod object using the addRequestHeader () method. The following IBM Systems Director specific entries need to be added to the request header:
        • Accept: Accept header with value as "application/json".
        • Accept-Language: Value can be any supported language. We have used en_us.
        • ISDAPIVersion: IBM Systems Director version "6.2.1.0".
        • Authorization: base64 converted username and password.
      3. Call HttpClient's execute method and pass the object of GetMethod to it.

      After updating HttpClient, you need to write your own client to call the sendGetRequest method of HttpClient class with URI as an argument. We have used to JUnit based tests to call the sendGetRequest method and check the return code.

      Listing 4. Listing 4. JUnit test case to test GET
      private DWHttpClient httpClient = null;
      String hostURI = null;
      
      @Test
      public void testListRes()
      {
      	httpClient = new DWHttpClient();
      	properties = new Properties();
      	try {
      		hostURI =
      		"https://1.2.3.4:8422/ibm/director/rest/resources/System";
      		statusCode = httpClient.sendGetRequest(hostURI);
      		assertEquals(HttpStatus.SC_OK, statusCode);
      } catch (Exception e) {
      	fail("unexpected exception has happened "+e.getMessage());
      		e.printStackTrace();
      	}
      }

      In the code in Listing 4, we have first initialized the object of the HttpClient class, which we have modified in code Listing 3. Then we have initialized the hostURI, which is used to retrieve the resource information from IBM Systems Director, and at last, called the sendGetRequest() method to run the GET request.

      We have checked the status code using the assertEquals() method of JUnit by verifying it against HttpStatus.SC_OK which actually means a return code of 200.

    2. Discover resources (POST operation):

      This POSToperation discovers a resource in IBM Systems Director. For running POST requests for IBM Systems Director, we need to modify the sendPostRequest method of HttpClient for IBM Systems Director related entries and also write our own client to invoke the request and check the result. Code snippets for sendPostRequest and client are shown in Listing 5:

      Listing 5. sendPostRequest method in HttpClient.java
      		.
      		.
      		.
      sendPostRequest(String hostURI, String requestData){
      	PostMethod method = new PostMethod(uri);
      		
      	method.addRequestHeader(new Header("Content-Type","application/json"));
      	method.setRequestEntity	(new StringRequestEntity
      		(requestData, "application/json", "UTF-8"));
      	method.addRequestHeader	(new Header
      		("Authorization", "Basic cm9vdDpnbzRicm9rZQ=="));
      	method.addRequestHeader(new Header("ISDAPIVersion", "6.2.1.0"));
      
      	int statusCode = client.executeMethod(method); 
      	return statusCode;
      }

      In the code snippet in Listing 5, you can see the following information:

      1. Initialize a object of PostMethod and pass the URI to it.
      2. Add the Request header to the PostMethod object with Content-Type, Authorization and ISDAPIVersion.
      3. Set a Request Entity to pass the request data.
      4. Finally run the method by passing the PostMethod object.

      The JUnit based client to invoke the POST request is as shown in Listing 6:

      Listing 6. JUnit testcase to test POST
      private DWHttpClient httpClient = null;
      String hostURI = null;
      
      @Test
      public void testDiscovery()
      {
      	httpClient = new DWHttpClient();
      	try {
      		hostURI = "https://1.2.3.4:8422/ibm/director/rest/discover";
      		String requestData = "{\"IPAddress\": [\"5.6.7.8\"],
      			\"ResourceTypes\": [\"Server\", \"OperatingSystem\"]}";
      		statusCode = httpClient.sendPostRequest(hostURI, requestData);
      		assertEquals(HttpStatus.SC_CREATED, statusCode);
      	} catch (Exception e) {
      		fail("unexpected exception has happened "+e.getMessage());
      		e.printStackTrace();
      	}
      }

      In the code in Listing 6, we first initialized the object of the HttpClient class, which we have modified in code Listing 5. Then we have initialized the hostURI, which is used to discover the resource mentioned in the request data.

      In the next step, we called the sendPosttRequest() method of HttpClient with hostURI and requestData as arguments and then we are checking the return code using the assertEquals() method. After successful execution of the request, it returns a code 201, which means "CREATED".

      As POST is an asynchronous operation, you need to track the progress of the job, so for that purpose, it always returns the location as part of the header. You need to retrieve the response header from the response object returned by the request. You can use the value of the location header to check the progress. Please refer the sample class in the download section for the complete code.

    3. Modify resource (PUT operation):

      The PUT request is used when you need to modify the resource. For running PUT requests for IBM Systems Director, we need to modify the sendPutRequest method of HttpClient for IBM Systems Director related entries and also write our own client to invoke the request and check the result. Code snippets for sendPutRequest and the client are shown in code Listing 7.

      Listing 7. sendPutRequest method in HttpClient.java
      		.
      		.
      		.
      sendPutRequest(String uri, String requestData){
      	PutMethod method = new PutMethod(uri);	
      
      	method.addRequestHeader(new Header
      		("Content-Type","application/json"));
      	method.addRequestHeader(new Header("ISDAPIVersion", "6.2.1.0"));
      	method.setRequestEntity(new StringRequestEntity
      		(requestData, "application/json", "UTF-8"));
      	method.addRequestHeader(new Header
      				("Authorization", "Basic cm9vdDpnbzRicm9rZQ=="));
      
      	int statusCode = client.executeMethod(method); 
      	return statusCode;
      }

      The JUnit based client to invoke the PUT request is as shown in code Listing 8:

      Listing 8. JUnit testcase to test PUT
      private DWHttpClient httpClient = null;
      String hostURI = null;
      
      @Test
      public void testModifyResource() throws IOException
      {
      	httpClient = new DWHttpClient();
      	hostURI = 
      		"https:1.2.3.4:8422/ibm/director/rest/resources/Server/12345";
      	String requestData = "
      			{\"Properties\": {\"DisplayName\" : \"NewResName\"}}";
      	statusCode = httpClient.sendPutRequest(hostURI, requestData);
      	assertEquals(HttpStatus.SC_NO_CONTENT,statusCode);
      }

      After successful execution of the request, IBM Systems Director returns a code 204 as shown in the code Listing 8

    4. Delete resource (DELETE operation):

      The DELETE operation is used when you need to delete a resource. You need to append the OID of the resource that you want to remove to the URI itself. For running the DELETE request for IBM Systems Director, we need to modify the sendDeleteRequest method of HttpClient for IBM Systems Director related entries and also write our own client to invoke the request and check the result. Code snippets for sendDeleteRequest and client are shown below:

      Listing 9. sendDeleteRequest method in HttpClient.java
      		.
      		.
      		.
      sendDeleteRequest(String uri){
      DeleteMethod method = new DeleteMethod(uri);		
      method.addRequestHeader(new Header
      			("Authorization", "Basic cm9vdDpnbzRicm9rZQ=="));
      method.addRequestHeader(new Header("ISDAPIVersion", "6.2.1.0"));
      
      int statusCode = client.executeMethod(method); 
      return statusCode;
      }

      The JUnit based client to invoke the DELETE request is as shown below:

      Listing 10. JUnit testcase to test DELETE
      private DWHttpClient httpClient = null;
      String hostURI = null;
      
      @Test
      public void testDiscovery() throws IOException
      {
      	httpClient = new DWHttpClient();
      	hostURI = 
      		"https://1.2.3.4:8422/ibm/director/rest/resources/Server/12345";
      	statusCode = httpClient.sendDeleteRequest(hostURI);
      	assertEquals(HttpStatus.SC_NO_CONTENT, statusCode);
      }

      After successful execution of the request, IBM Systems Director returns a 204 code as shown in the code Listing 10.

Sample code to automate REST API tests using the HTTP client

We have written sample code for all the scenarios mentioned in the tutorial along with some additional POST operation scenarios. This code can be downloaded from the download section of this tutorial. This code includes the following parts:

  • List Resources (GET Operation)
  • Discover a new resource (POST Operation)
  • Request access to discovered resource (POST Operation)
  • Collect inventory (POST Operation)
  • Modify Resource (PUT Operation)
  • Delete Resource (DELETE Operation)

Sample code can be reused if required. This code also contains some utility classes and properties file as mentioned below:

  • HttpClient: This class defines all the HTTP operations, like GET, POST, PUT and DELETE. This class also contains the code for certificate verification for the director server.
  • HttpResponse:This class is to format the HTTP response.
  • Read Properties file: This class is to read the properties from the properties file.
  • Util: This class contains some utility methods to retrieve the OID for the resource and so on.
  • config.properties: This file has properties that vary from system to system.

To make the code more flexible and reusable, we have introduced a properties file where you can enter the IBM Systems Director and all endpoint information. Testcases read this properties file at the run time to retrieve this information. This code can run on any system by just updating the properties file.

You can run the individual classes for performing any specific operation. We have also introduced one TestSuite file to run all the scripts at one go.

We have created a ISDSuite file and launched the suite file to run all the tests from Eclipse. Figure 10 shows the result of the execution.

Figure 10. Result of JUnit TestSuite execution
Alternative text for image

You can also run all the tests from the command prompt as well using the following command:

java org.junit.runner.JUnitCore ISDSuite

There are a few important points to note:

  1. For running the REST API, you need to convert the combination of the user name and password to base 64 encoding always.
    • For Linux®: You need to use the following format: usrename:password

      Convert the mentioned string to the base 64 encoding and append "Basic" before the string before putting it in Authorization header. For example, Basic "Base64 converted string"

    • For Microsoft® Windows®: User need to use the following format: domain\\usrename:password

      Convert the mentioned string to the base 64 encoding and append "Basic" before the string before putting it in Authorization header. For example, Basic "Base64 converted string"

  2. IBM Systems Director certificate: The DWHttpClient class takes care of the creation of the certificate for the remote systems to make a secure call.

Resources

Learn

Get products and technologies

Discuss

More downloads

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
ArticleID=812286
ArticleTitle=How to test REST APIs for IBM Systems Director using Java
publish-date=05072012