Interactive tool to run REST APIs of IBM Systems Director

This article covers the interactive tool to run Representational State Transfer (REST) application programming interfaces (APIs) of IBM® Systems Director VMControl™. This tool provides a command-line interface (CLI) interface to invoke REST APIs for IBM Systems Director VMControl.

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

Piyush Jain Piyush 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 around 6 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


developerWorks Contributing author
        level

19 December 2012

Also available in Chinese

Section 1. Before you start

Objectives

The main objective of this article is to help developers and testers working on IBM Systems Director to run the IBM Systems Director VMControl REST APIs without using any external client on the Linux® computer using the CLI.

Prerequisites

You should have IBM Systems Director V6.x.x installed on your computer before proceeding. This article assumes that you are familiar with using IBM Systems Director. It also assumes that you have a reasonable understanding of REST APIs and Python.

System requirements

You need to perform the following tasks on your computer:

  • Configure IBM Systems Director
  • Install Python 2.7.2

In addition to the above requirements, user must also:

  • Install a python module, httplib2 (httplib2-0.7.2.tar.gz) on top of python 2.x.x.
    • gunzip httplib2-0.7.2.tar.gz
    • tar -xvf httplib2-0.7.2.tar
    • cd httplib2-0.7.2
    • python setup.py install
  • Update the environment.json file before the user runs any of these requests. This is the configuration file which holds the information related IBM Systems Director IP address, System Director credentials, and Systems Director API version. User need to update the following fields in the file:
    • ISD_IP
    • ISDUser
    • ISDPassword
    • ISDAPIVersion

Section 2. How to run REST APIs for IBM Systems Director using this tool

About REST APIs

REST stands for Representational State Transfer. REST-style architectures consist of clients and servers. IBM Systems Director also provides an interface based on RESTful web services. 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 Hypertext Transfer Protocol (HTTP) protocol. It supports the following HTTP methods:

  • 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.

About the tool

The tool is written in Python. Python has an added advantage as it is defaulted with Linux and is easy to use. The interactive tool offers simple menus that helps users (with the basic knowledge about REST APIs and the URIs) to effectively use the tool. User might have to select the different options to run an operation. To run any REST request manually, various external clients, such as HTTP4e, REST client, Firefox poster, and so on, are available. Users should know how to use these clients, URI, and the HTTP header for a particular request. With the advent of this tool, any user with little or no information about REST APIs can perform various operations simply by selecting the menus. For the GET request, users will be able to directly select the operation to run. For PUT and POST requests, the tool provides additional help. Users can run the related GET requests to retrieve the object identifiers (OIDs) and other values. Users can also list the sample JavaScript Object Notations (JSONs) to form there own JSON. For a DELETE request, A user can get the list of OIDs for a particular resource to perform the delete operation. This tool uses a configuration file, where the user can specify the system details.

One of the biggest advantages of using this tool is that the user can perform the function on multiple machines from one terminal. The tool supports almost all the System Director VMControl operations, employing REST API functionality and some selected Base IBM Systems Director functionality. This tool can be used to design clients for building cloud-related services such as deploy, capture, provision, and so on.

Tool categories

Run the base Director functions: It has limited support for base director functions, such as:

  • Discovery
  • Request
  • Collect inventory

All three functions mentioned above are prerequisites to perform Systems Director VMControl functions.

Here is the first example that illustrates how to collect inventory to a system through REST APIs and later track the job for the same.

[root@rcc-pok-idg-2214 piyush]# python REST_Client_ISD_VMC.pyc
=================================================
Welcome to REST Client for IBM Systems Director
and VMControl, Let's Play
Script : Python
Author : Piyush Jain
E-Mail : piyushjain@in.ibm.com
=================================================
    Select Operation :
    1. IBM Systems Director Menu
    2. VMControl Menu
    3. Quit

Select the action you want to perform: 1
=========================
IBM Systems Director Menu
=========================
    Select Operation :

    1. Discover a Resource
    2. Request Access a Resource
    3. Collect Inventory
    4. Go Back to the Previous Menu
    5. Quit

Select the action you want to perform: 3
=========================================
    Collect Inventory Menu:

    1. View sample JSON collecting inventory
    2. Start Collect Inventory
    3. List the status of the Collect Inventory
    4. Go Back to the Previous Menu
    5. Quit

Select your choice: 1
Example 1:

{"DisplayName": "My inventory collection"}
=========================================
    Collect Inventory Menu:

    1. View sample JSON collecting inventory
    2. Start Collect Inventory
    3. List the status of the Collect Inventory
    4. Go Back to the Previous Menu
    5. Quit

Select your choice: 2
Enter the oid of the resource: 2939
Enter the json for collect inventory: {"DisplayName": "My inventory collection"}

==========
INPUTS :
==========
URI  : https://9.12.181.49:8422/ibm/director/rest/resources/OperatingSystem/
       2939/inventoryprofiles/default.All/inventory/jobs
JSON : {"DisplayName": "My inventory collection"}

===========
RESULT :
===========
{'status': '201', 'content-length': '0', 'content-language': 'en-us',
 'set-cookie': 'JSESSIONID_ibm_console_80=0000WezuGMm0QJBklO_wGBCZUKf;Path=/; 
 Secure; HTTPOnly,  AUTH_JSESSIONID=3shq0mn0kehhrfra521s74c49i5;Path=/; HTTPOnly',
 'accept-ranges': 'bytes', 'expires': 'Thu, 01 Dec 1994 16:00:00 GMT',
 'server': 'Noelios-Restlet-Engine/1.1.4',
 'location': 'https://9.12.181.49:8422/ibm/director/rest/jobs/157',
 'cache-control': 'no-store', 'date': 'Mon, 17 Sep 2012 04:07:47 GMT',
 'content-type': 'text/html; charset=ISO-8859-1'}

======================================================================

    Collect Inventory Menu:

    1. View sample JSON collecting inventory
    2. Start Collect Inventory
    3. List the status of the Collect Inventory
    4. Go Back to the Previous Menu
    5. Quit


Select your choice: 3
Enter the uri to check the status of your job:
https://9.12.181.49:8422/ibm/director/rest/jobs/157

==========
INPUTS :
==========
URI  : https://9.12.181.49:8422/ibm/director/rest/jobs/157
===========
RESULT :
===========
{'status': '200', 
 'content-location': 'https://9.12.181.49:8422/ibm/director/rest/jobs/157',
 'content-language': 'en-us', 'transfer-encoding': 'chunked',
 'set-cookie': 'JSESSIONID_ibm_console_80=0000LhUR0Bp8y82ouO2LPdBcEb1;Path=/;
 Secure; HTTPOnly,  AUTH_JSESSIONID=225r1kma3drkh44mhi7egqbmme1;Path=/; HTTPOnly',
 'accept-ranges': 'bytes', 'expires': 'Thu, 01 Dec 1994 16:00:00 GMT',
 'server': 'Noelios-Restlet-Engine/1.1.4', 'etag': '"43114311"',
 'cache-control': 'no-store', 'date': 'Mon, 17 Sep 2012 04:08:07 GMT',
 'content-type': 'application/json; charset=UTF-8'}
{"uri":"/ibm/director/rest/jobs/157", "DisplayName":"My inventory collection",
"JobID":157,"Description":"Run once on 9/17/12 at 12:07 AM",
"Tasks":["/ibm/director/rest/tasks/INVENTORY_TASK"],
"Targets":["/ibm/director/rest/resources/OperatingSystem/2939"],
"Activations":"/ibm/director/rest/jobs/157/activations",
"LastRunStatus":"Active","LastRun":1347854866883,
"LastRunProgress":84,"NextRun":null,"CreatedBy":"root"}

====================================================================
    Collect Inventory Menu:

    1. View sample JSON collecting inventory
    2. Start Collect Inventory
    3. List the status of the Collect Inventory
    4. Go Back to the Previous Menu
    5. Quit

Select your choice: 5
[root@rcc-pok-idg-2214 piyush]#

So, here we have extended help (such as listing the sample JSON to launch the job) available for the user. For the POST and PUT operations, users can track the jobs, as shown in the first example.

Here is the sequence of the action performed in the first example:

  1. Select the Base Director menu option.
  2. Select the collect inventory operation.
  3. View the sample JSON for the collect inventory POST request.
  4. Launch the collect inventory operation.
  5. View the status of the job launched for collecting inventory.
  6. Exit.

Run VMControl functions: It has support for the following VMControl resources. Users can perform all the operations, such as getting the information about the resource, creating a resource, modifying a resource, and deleting a resource.

  • Host
  • Virtual servers
  • Workload
  • System pool
  • Repository
  • Virtual appliances

Here is the second example that illustrates how to create a workload and track a job after the creation of the workload.

[root@rcc-pok-idg-2214 piyush]# python REST_Client_ISD_VMC.pyc
=================================================
Welcome to REST Client for IBM Systems Director
and VMControl, Let's Play
Script : Python
Author : Piyush Jain
E-Mail : piyushjain@in.ibm.com
=================================================
    Select Operation :
    1. IBM Systems Director Menu
    2. VMControl Menu
    3. Quit

Select the action you want to perform: 2
===============================
IBM Systems Director VMControl
===============================
    Select Operation :

    1. Create a Resource
    2. Modify a Resource
    3. Delete a Resource
    4. List a Resource
    5. Go Back to the Previous Menu
    6. Quit

Select the action you want to perform: 1
=========================================
    Create Resource Menu:

    1. Create Virtual Servers
    2. Create Workloads
    3. Create Virtual Appliances
    4. Create Repository
    5. Create Server System Pool
    6. Go Back to the Previous Menu
    7. Quit

Select your choice: 2
=========================================
    Create Workload Menu:

    1. Using Virtual Server
    2. Deploy a Virtual Appliance
    3. Go Back to the Previous Menu
    4. Quit

Select your choice: 1
=========================================
    Create Workload using Virtual Server Menu:

    1. List Virtual Servers
    2. View sample JSON to create Workload using Virtual Server
    3. Create Working Using Virtual Server
    4. List the status of the create workload Request
    5. Go Back to the Previous Menu
    6. Quit

Select your choice: 1
==========
INPUTS :
==========
URI  : https://9.12.181.49:8422/ibm/director/rest/VMControl/virtualServers
===========
RESULT :
===========
{'status': '200', 'content-length': '1168', 
'content-location': 
u'https://9.12.181.49:8422/ibm/director/rest/VMControl/virtualServers',
'content-language': 'en-us', 
'set-cookie': 
'JSESSIONID_ibm_console_80=0000_VKrZuyB8OpOqeQOFjav8m9;Path=/; Secure; HTTPOnly,
 AUTH_JSESSIONID=1s7204b52823o4rn32g32q65ac1;Path=/; HTTPOnly', 
'accept-ranges': 'bytes', 'expires': 'Thu, 01 Dec 1994 16:00:00 GMT',
 'server': 'Noelios-Restlet-Engine/1.1.4', 'etag': '"2109597345"',
 'cache-control': 'no-store', 'date': 'Mon, 17 Sep 2012 05:55:51 GMT', 
'content-type': 'application/json; charset=UTF-8'}
{"virtualServers":
[{"uri":"\/ibm\/director\/rest\/VMControl\/hosts\/15546\/virtualServers\/15551",
"oid":15551,"name":"AIX207","state":{"label":"Started","id":8},
"customization":
{"uri":
"\/ibm\/director\/rest\/VMControl\/hosts\/15546\/virtualServers\/15551\/customization"},
"properties":{}}],"uri":"\/ibm\/director\/rest\/VMControl\/virtualServers"}
================================================================================
    Create Workload using Virtual Server Menu:
    1. List Virtual Servers
    2. View sample JSON to create Workload using Virtual Server
    3. Create Working Using Virtual Server
    4. List the status of the create workload Request
    5. Go Back to the Previous Menu
    6. Quit

Select your choice: 2
Example 1:

{"workload": {"name": "workload_1", "server": 1234, 
"description": "This is a workload"}}

Example 2:

{"workload": {"name": "workload_1", "servers": [4599, 4600, 4601], 
"description": "This is a workload"}}
=========================================
    Create Workload using Virtual Server Menu:

    1. List Virtual Servers
    2. View sample JSON to create Workload using Virtual Server
    3. Create Working Using Virtual Server
    4. List the status of the create workload Request
    5. Go Back to the Previous Menu
    6. Quit

Select your choice: 3
Enter the input json to create a workload using virtual servers: 
{"workload": {"name": "workload_1", "server": 15551, "description": "This is a workload"}}

==========
INPUTS :
==========
URI  : https://9.12.181.49:8422/ibm/director/rest/VMControl/workloads
JSON : {"workload": {"name": "workload_1", "server": 15551, 
"description": "This is a workload"}}

===========
RESULT :
===========
{'status': '201', 'content-length': '46', 'content-language': 'en-us', 
'set-cookie': 
'JSESSIONID_ibm_console_80=0000DonDzXSvbkOJocmMgTTKsrP;Path=/; Secure; HTTPOnly,
 AUTH_JSESSIONID=4cqas97nift2kpormrn509n0h90;Path=/; HTTPOnly', 
'accept-ranges': 'bytes', 'expires': 'Thu, 01 Dec 1994 16:00:00 GMT', 
'server': 'Noelios-Restlet-Engine/1.1.4',
 'location': 'https://9.12.181.49:8422/ibm/director/rest/VMControl/workloads/15647', 
'cache-control': 'no-store', 'date': 'Mon, 17 Sep 2012 05:56:06 GMT', 
'content-type': 'application/octet-stream; charset=UTF-8'}
DNZEMW350I Workload [15647] creation started.
======================================================================================
    Create Workload using Virtual Server Menu:
    1. List Virtual Servers
    2. View sample JSON to create Workload using Virtual Server
    3. Create Working Using Virtual Server
    4. List the status of the create workload Request
    5. Go Back to the Previous Menu
    6. Quit

Select your choice: 4
Enter the uri to check the status of your job: 
https://9.12.181.49:8422/ibm/director/rest/VMControl/workloads/15647

==========
INPUTS :
==========
URI  : https://9.12.181.49:8422/ibm/director/rest/VMControl/workloads/15647

===========
RESULT :
===========
{'status': '200', 'content-length': '1071', 
'content-location': 
'https://9.12.181.49:8422/ibm/director/rest/VMControl/workloads/15647',
 'content-language': 'en-us',
 'set-cookie': 
'JSESSIONID_ibm_console_80=0000tsdpxtr0njR0nYHROmgHJyT;Path=/; Secure; HTTPOnly,
 AUTH_JSESSIONID=95fg36cdjsqrr16ensj4ipnodq;Path=/; HTTPOnly', 'accept-ranges': 'bytes',
 'expires': 'Thu, 01 Dec 1994 16:00:00 GMT', 'server': 'Noelios-Restlet-Engine/1.1.4',
 'cache-control': 'no-store', 'date': 'Mon, 17 Sep 2012 05:56:21 GMT',
 'content-type': 'application/json; charset=UTF-8'}
{"virtualServerCount":1,"detailedState":0,"changedDate":1347861365000,
"approvalRequired":true,
"metrics":{"uri":
"\/ibm\/director\/rest\/resources\/WorkloadInstance\/15647\/monitorviews\/
WORKLOAD_METRICS_GROUP_ID\/monitordata"},"suspendResumeCapable":false,
"priority":2,"virtualServers":
{"uri":"\/ibm\/director\/rest\/VMControl\/workloads\/15647\/virtualServers"},
"resilient":"None","systemPools":
{"uri":"\/ibm\/director\/rest\/VMControl\/workloads\/15647\/systemPools"},
"vendor":"UNDEFINED","remoteRestart":false,"liveVirtualServerRelocation":false,
"oid":15647,"name":"workload_1","hosts":
{"uri":"\/ibm\/director\/rest\/VMControl\/workloads\/15647\/hosts"},
"uri":"\/ibm\/director\/rest\/VMControl\/workloads\/15647",
"info":"UNDEFINED","state":{"label":"Started","id":8},
"properties":{"State":"Started","ApprovalRequired":true,
"ChangedDate":1347861365000,"Resilient":false,"SpecificationVersion":null,
"Vendor":{},"Oid":15647,"Name":"workload_1","Description":"This is a workload",
"Info":{}},
"specificationVersion":null,"description":"This is a workload","createdBy":"root"}
===================================================================================
Create Workload using Virtual Server Menu: 1. List Virtual Servers
2. View sample JSON to create Workload using Virtual Server
3. Create Working Using Virtual Server
4. List the status of the create workload Request
5. Go Back to the Previous Menu
6. Quit Select your choice: 6 [root@rcc-pok-idg-2214 piyush]#

Here is the sequence of the action performed in the second example:

  1. Select the VMControl menu option.
  2. Select the create resource operation.
  3. Select the create workload resource operation.
  4. Select to create a workload using a virtual server.
  5. Select to list the available virtual servers to create the workload.
  6. View the sample json for the create workload POST request.
  7. Launch the create workload operation.
  8. View the status of the workload created.
  9. Exit.

So, this tool provides the best understanding of the flow to create a resource with easy and interactive options. See Figure 1 for the tool’s flow.

Tool's flow diagram:
Tool's flow diagram:

Figure 1: REST client for IBM Systems Director and VMControl

As shown in Figure 1, the user has to first select the operation to be performed (that is GET, PUT, POST or DELETE). Then, select the resource and operation respectively. User will get the response immediately on the screen.

This tool has the following advantages:

  1. Is easy to use and simple to run the REST request
  2. Is extendable
  3. Includes an in-build help to foam a JSON to run the PUT and POST requests
  4. Helps to retrieve the OIDs and other values
  5. Enables better understanding of the flow as it is an interactive tool
  6. Provides simple menus to select the correct operation
  7. Tracks the jobs after running the POST, PUT, and DELETE operations

Resources

Learn

Get products and technologies

Discuss


Download

DescriptionNameSize
Demo:Code for the interactive tool to run REST APIrest_client.zip95 KB

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=852092
ArticleTitle=Interactive tool to run REST APIs of IBM Systems Director
publish-date=12192012