Download as pdf or txt
Download as pdf or txt
You are on page 1of 18

Managing your private cloud, Part 2: Using the

WebSphere CloudBurst REST API interface


Skill Level: Introductory

Dustin Amrhein
Staff Software Engineer
IBM

Xi Ning Wang (wangxn@cn.ibm.com)


Software Engineer
IBM

04 Nov 2009

Several interface options are available to help you to interact with the IBM®
WebSphere® CloudBurst™ Appliance, which provides functionality for creating,
deploying, and managing IBM WebSphere Application Server virtual systems in a
private cloud. These interfaces include a Web 2.0 graphical user interface, a Jython
command line interface, and an HTTP REST API. This article discusses the HTTP
REST API, which provides a language-neutral interface that is ideal for integrating
WebSphere CloudBurst capabilities into existing applications or user interfaces.

Introduction
The IBM WebSphere CloudBurst Appliance provides you with the capability to
manage the full lifecycle of WebSphere Application Server virtual systems in a
private cloud, including the ability to create, deploy, and manage such virtual
systems.

Three user interfaces enable you to leverage the function of the appliance:

• The Web 2.0 graphical user interface (GUI) is generally the right fit for
infrequently performed actions or for introducing new users to the
capabilities of the appliance.

Using the WebSphere CloudBurst REST API interface


© Copyright IBM Corporation 2009. All rights reserved. Page 1 of 18
developerWorks® ibm.com/developerWorks

• The command line interface, described in Part 1, provides a Jython


interface with which commonly performed tasks can be automated.
• The REST API is ideal for integrating the appliance into existing
applications and user interfaces. The use of the REST API does not imply
the use of a certain technology or programming language on the client. In
fact, since the API is used by issuing HTTP URL requests, the interface
can be accessed from Java™, C++, PHP, JavaScript™, Groovy, and a
host of other environments.
The WebSphere CloudBurst REST API equips you with a means with which you
interact with the appliance that is both language neutral and programming model
neutral. When using the REST API, you interact with the resources of the appliance
(hypervisors, patterns, script packages, and so on) entirely by using well-defined
HTTP URLs and associated HTTP verbs (GET, POST, PUT, DELETE). Using this
simple interface you can perform many of the appliance’s capabilities for managing
WebSphere Application Server environments in a private cloud.

Preparing to use the REST API


Before you begin working with the WebSphere CloudBurst REST API, take a
moment to understand a few basics about this interface.

First, every WebSphere CloudBurst Appliance provides the WebSphere CloudBurst


REST API out of the box; there is no feature you need to enable to use the API. The
API is accessible on the same host as the appliance, but all API requests must be
sent using the HTTPS protocol, and they must be sent to port 443. The appliance
does use self-signed SSL certificates, so it is important that you configure your client
appropriately. Clients can either choose to accept or ignore this certificate.

When using the REST API, you also need to be aware of certain HTTP headers that
are required in every request. Table 1 provides a listing of those headers and a brief
explanation of their use.

Table 1. Required HTTP request headers


Header name Description
Accept The appliance generally sends back JSON (Java
Script Object Notation) encoded data in all
responses. Clients should set application/json as
the Accept value for all requests.
Accept-Language This parameter indicates the language or locale
to be used when generating responses.
Authorization The REST API supports basic authentication.
The same user IDs and passwords configured for
users in the appliance should be used when

Using the WebSphere CloudBurst REST API interface


Page 2 of 18 © Copyright IBM Corporation 2009. All rights reserved.
ibm.com/developerWorks developerWorks®

sending requests to the REST API. The


permissions and access granted to users of the
appliance are the same regardless of the
interface that is used.
Content-Type All data sent via the REST API must be JSON
encoded. As such, clients that send data in
requests should set application/json as the
Content-Type value.
X-CloudBurst-API-Version This specifies the version of the WebSphere
CloudBurst REST API being used. As of the date
of publication, the only valid value is 1.0.

The remainder of this article presents examples that illustrate how the WebSphere
CloudBurst REST API can be used, specifically to:

• Setup a private cloud: Define a hypervisor to the appliance, associate IP


addresses with the hypervisor, create a cloud group containing the
hypervisor, and ensure the hypervisor is properly initialized and ready for
deployments.
• Retrieve a pattern: Retrieve all the patterns available for deployment and
deploy a selected pattern to a defined cloud group.
• Deploy patterns to the cloud: Query virtual systems to gather information
about WebSphere Application Server virtual systems (cells) that have
been deployed by a particular WebSphere CloudBurst Appliance.
This article illustrates how to use the WebSphere CloudBurst REST API by sending
HTTP requests. This API is formed by the combination of a URL, HTTP method,
HTTP request headers, and, in some cases, an HTTP request body. These
components are labeled as such in the listings below that show REST API requests.
In addition, several listings are provided that show the HTTP responses you can
expect from such requests. In these HTTP responses, only the body of the returned
response is shown, in JSON format. HTTP response headers are omitted because,
in many cases, they are not important to the content being displayed. When an
HTTP response header is important, it will be noted in the text.

This article does not dictate the use of any particular HTTP client to make these
requests. In fact, any client (programattic or otherwise) that is capable of sending
HTTP requests with the headers and body format specified in this article can be
used to communicate with the WebSphere CloudBurst Appliance through the REST
API.

For the purpose of illustrating the results of the HTTP requests that are shown here,
screen captures of the graphical user interface are also presented on occasion.
Also, these examples assume that the appliance is available using the
mycloudburst.com host name.

Using the WebSphere CloudBurst REST API interface


© Copyright IBM Corporation 2009. All rights reserved. Page 3 of 18
developerWorks® ibm.com/developerWorks

Setup a private cloud


In this example, the REST API will be used to setup the private cloud to be used by
the appliance. This involves:

• Creating a hypervisor.
• Adding the hypervisor to a cloud group.
• Defining an IP group to be used by the hypervisor.
To carry out these actions using the REST API, you must be a user with at least
Cloud Administration role permissions.

1. The first step is to create a hypervisor resource that is contained within


the Functional Test Cloud cloud group (Listings 1a and 1b).
Listing 1a. Add a hypervisor resource - Request

URL: https://mycloudburst.com:443/resources/hypervisors
HTTP Method: POST
HTTP request headers:
HTTP Body:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"address": "ftchypervisor-1.com",
"name": "Functional test hypervisor - 1",
"password": "ftpassword",
"type": "ESX",
"userid": "ftuser"
}

Listing 1b. Add a hypervisor resource - Response

{
"desiredstatus_text": "Maintenance mode",
"currentstatus_text": "Maintenance mode",
"networks": [
],
"userid": "root",
"certified": "I",
"created": 1251407372817,
"name": "Functional test hypervisor - 1",
"currentstatus": "RM01025",
"desiredstatus": "RM01025",
"currentmessage": "RM03106",
"address": "https://ftchypervisor-1.com/sdk",
"cloud": null,
"type": "ESX",
"storage": [

Using the WebSphere CloudBurst REST API interface


Page 4 of 18 © Copyright IBM Corporation 2009. All rights reserved.
ibm.com/developerWorks developerWorks®

],
"updated": 1251407372817,
"id": 5,
"password": "125140737281455",
"currentmessage_text": "Maintenance mode (must add to a cloud group to start)"
}

Take note of the address attribute’s value as the appliance automatically


configures the address based on the host name provided. All VMware
ESX or ESXi hypervisor addresses follow the pattern of
https://<hypervisor_host>/sdk. Although the HTTP response
headers are not shown in Listing 1b (as is normal with HTTP POST
requests) an HTTP Location header is returned in the response
(resources/hypervisors/5 in our case). This is the URI for the hypervisor
resource that you just created. This value will be used in some of the next
requests.

2. Next, you need to accept the SSL certificate of the hypervisor that you
just created. To do this, you need to send an HTTP GET request to the
resources/hypervisors/<hypervisor_id>certificate URL.
For the hypervisor above, you could accept the certificate by sending a
GET request to the
https://mycloudburst.com:443/resources/hypervisors/5/certificate
URL. The contents of the SSL certificate are returned in the HTTP
response body sent back as a result of this GET request. After issuing
this request, send a PUT request to the hypervisor, updating the value of
the certified attribute from I to T (Listing 2). This PUT request indicates
that the SSL certificate for this hypervisor resource has been accepted.
Listing 2. Accept the SSL certificate - Request

URL: https://mycloudburst.com:443/resources/hypervisors/5
HTTP Method: PUT
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"desiredstatus_text": "Maintenance mode",
"currentstatus_text": "Maintenance mode",
"networks": [
],
"userid": "root",
"certified": "T",
"created": 1251408002475,
"name": "Functional test hypervisor - 1",
"currentstatus": "RM01025",
"desiredstatus": "RM01025",
"currentmessage": "RM03106",
"address": "https://ftchypervisor-1.com/sdk",
"cloud": null,

Using the WebSphere CloudBurst REST API interface


© Copyright IBM Corporation 2009. All rights reserved. Page 5 of 18
developerWorks® ibm.com/developerWorks

"type": "ESX",
"storage": [
],
"updated": 1251408002475,
"id": 5,
"password": "125140800247456",
"currentmessage_text": "Maintenance mode (must add to a cloud group to start)"
}

Now that you have accepted the SSL certificate associated with the
hypervisor and changed the state of the hypervisor resource to indicate
this acceptance, WebSphere CloudBurst will begin to automatically detect
the storage and networks for the hypervisor. Once the storage and
networks have been detected, the appropriate attributes will be
automatically updated on the hypervisor resource.

3. The next step in setting up your private cloud is to add your newly created
hypervisor to a cloud group. To do this, you will first create a resource
representing the cloud group (Listings 3a and 3b).
Listing 3a. Create a new cloud group - Request

URL: https://mycloudburst.com:443/resources/clouds
HTTP Method: POST
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"defaultcloud": "F",
"description": "Functional Test Cloud",
"name": "FTC",
"vendor": "ESX"
}

Listing 3b. Create a new cloud group - Response

{
"defaultcloud": "F",
"created": 1251409447905,
"vendor": "ESX",
"updated": 1251409447905,
"name": "FTC",
"id": 4,
"hypervisors": [
],
"description": "Functional Test Cloud"
}

4. Next, follow up the POST request above with a PUT request indicating
that the new hypervisor is part of this cloud group. Do this by specifying

Using the WebSphere CloudBurst REST API interface


Page 6 of 18 © Copyright IBM Corporation 2009. All rights reserved.
ibm.com/developerWorks developerWorks®

the hypervisor’s URI in the hypervisors attribute of the cloud group


resource (Listing 4).
Listing 4. Add a hypervisor to a cloud group - Request

URL: https://mycloudburst.com:443/resources/clouds/4
HTTP Method: PUT
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"defaultcloud": "F",
"created": 1251409447905,
"vendor": "ESX",
"updated": 1251409447905,
"name": "FTC",
"id": 4,
"hypervisors": [“/resources/hypervisors/5”],
"description": "Functional Test Cloud"
}

After the above PUT request, Functional test hypervisor - 1 will belong to
the FTC cloud group.

5. To fully initialize your private cloud, create an IP group and a group of IP


addresses that can be utilized by your hypervisor. To create an IP group,
the send the POST request shown in Listings 5a and 5b.
Listing 5a. Create an IP group resource - Request

URL: https://mycloudburst.com:443/resources/ipGroups
HTTP Method: POST
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"gateway": "10.42.132.1",
"name": "FT IP Group",
"netmask": " 255.0.0.0",
"primarydns": " 10.16.15.253",
"secondarydns": " 10.16.15.253",
"subnetaddress": " 10.16.8.0"
}

Listing 5b. Create an IP group resource - Response

{
"gateway": "10.42.132.1",
"networks": [

Using the WebSphere CloudBurst REST API interface


© Copyright IBM Corporation 2009. All rights reserved. Page 7 of 18
developerWorks® ibm.com/developerWorks

],
"secondarydns": "10.16.15.253",
"subnetaddress": "10.16.8.0",
"primarydns": "10.16.15.253",
"created": 1251410587296,
"netmask": "255.0.0.0",
"updated": 1251410587296,
"name": "FT IP Group",
"id": 2
}

6. Next, you need to add a pool of IP addresses that are associated with this
IP group. You can do this by sending a POST request containing the IP
addresses (Listing 6).
Listing 6. Add IP addresses to an IP group - Request

URL: https://mycloudburst.com:443/resources/ipGroups/2/ips
HTTP Method: POST
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"addresses": ["10.1.2.3", "10.1.2.4"]
}

7. After the IP addresses have been added to the IP group resource, the
next step is to update the networks attribute on your IP group to point to
the relevant networks on your hypervisor. First, check the hypervisor
resource to ensure that the appropriate networks were detected after
accepting the hypervisor’s SSL certificate. You can do this by sending a
GET request for to the hypervisor resource (Listings 7a and 7b).
Listing 7a. Verify network discovery for the hypervisor - Request

URL: https://mycloudburst.com:443/resources/hypervisors/5
HTTP Method: GET
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0

Listing 7b. Verify network discovery for the hypervisor - Response

{
"desiredstatus_text": "Maintenance mode",
"currentstatus_text": "Maintenance mode",
"networks": [

Using the WebSphere CloudBurst REST API interface


Page 8 of 18 © Copyright IBM Corporation 2009. All rights reserved.
ibm.com/developerWorks developerWorks®

"/resources/networks/5",
"/resources/networks/6"
],
"userid": "root",
"certified": "T",
"created": 1251408002475,
"name": "Functional test hypervisor - 1",
"currentstatus": "RM01025",
"desiredstatus": "RM01025",
"currentmessage": "RM03109",
"address": "https://ftchypervisor-1.com/sdk",
"cloud": "/resources/clouds/4",
"type": "ESX",
"storage": [
"/resources/storage/5",
"/resources/storage/6"
],
"updated": 1251409727403,
"id": 5,
"password": "125140800247456",
"currentmessage_text": "Maintenance mode (must set an IP group
for a network to start)"
}

Notice that the networks attribute indicates two different resource URIs. If
you need to find out more information about the network resources, a
GET request to
https://mycloudburst.com:443/resources/networks/<network_id>
would return that information. In this case, you will associate the network
resource indicated by the /resources/networks/6 URI with the IP group by
sending the PUT request shown in Listing 8.

Listing 8. Associate IP groups with networks - Request

URL: https://mycloudburst.com:443/resources/ipGroups/2
HTTP Method: PUT
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"gateway": "10.42.132.1",
"networks": [“resources/networks/6”],
"secondarydns": "10.16.15.253",
"subnetaddress": "10.16.8.0",
"primarydns": "10.16.15.253",
"created": 1251410587296,
"netmask": "255.0.0.0",
"updated": 1251410587296,
"name": "FT IP Group",
"id": 2
}

This PUT request effectively associates the IP group with the hypervisor
containing the resources/networks/6 network resource. This means that

Using the WebSphere CloudBurst REST API interface


© Copyright IBM Corporation 2009. All rights reserved. Page 9 of 18
developerWorks® ibm.com/developerWorks

virtual machines started on the hypervisor will utilize the IP addresses


contained in this IP group.

8. After the above PUT request, the status of Functional test hypervisor - 1
can be updated from Maintenance Mode to Started state by updating the
desiredstatus attribute on the resource (Listings 9a and 9b).
Listing 9a. Update the hypervisor state - Request

URL: https://mycloudburst.com:443/resources/hypervisors/5
HTTP Method: PUT
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0

Listing 9b. Update the hypervisor state - Response

{
"desiredstatus_text": "Maintenance mode",
"currentstatus_text": "Maintenance mode",
"networks": [
"/resources/networks/5",
"/resources/networks/6"
],
"userid": "root",
"certified": "T",
"created": 1251408002475,
"name": "Functional test hypervisor - 1",
"currentstatus": "RM01025",
"desiredstatus": "RM01006",
"currentmessage": "RM03109",
"address": "https://ftchypervisor-1.com/sdk",
"cloud": "/resources/clouds/4",
"type": "ESX",
"storage": [
"/resources/storage/5",
"/resources/storage/6"
],
"updated": 1251409727403,
"id": 5,
"password": "125140800247456",
"currentmessage_text": "Maintenance mode (must set an IP group
for a network to start)"
}

The RM1006 code indicates the Started state, which means that the hypervisor was
started as a result of this PUT request. You can confirm this by retrieving the
resource via a GET request, or you can log into the WebSphere CloudBurst
administrative console and view the hypervisor. If you do the latter, you should see
the current status is Started state (Figure 1).

Figure 1. Hypervisor in the WebSphere CloudBurst console

Using the WebSphere CloudBurst REST API interface


Page 10 of 18 © Copyright IBM Corporation 2009. All rights reserved.
ibm.com/developerWorks developerWorks®

Retrieve a pattern
A pattern in the WebSphere CloudBurst Appliance is a complete representation of a
WebSphere Application Server environment. It contains parts that represent different
WebSphere Application Server nodes (such as deployment managers, custom
nodes, standalone servers, and so on), as well as script packages that enable users
to customize the middleware environment. These script packages can be used to
include any desired customization to the server’s configuration, even including the
installation of user applications into the environment. These patterns are saved on
the appliance, and can be shared and reused to produce consistent, repeatable
WebSphere Application Server deployments.

WebSphere CloudBurst provides preloaded patterns that you can use as is, or that
you can copy and customize to create new patterns more suitable to your
environment. The WebSphere Application Server cluster pattern, for example, is a
WebSphere Application Server topology for large scale development or production
environments, and consists of a deployment manager, two custom nodes, and an
IBM HTTP server. Each of these parts resides in its own virtual machine.

As with other WebSphere CloudBurst resources, you can use the REST API for
interacting with and taking actions on the patterns stored on the appliance.

Use the REST API to retrieve the cluster pattern (Listing 10a). The response in
Listing 10b represents the properties and values returned by WebSphere
CloudBurst.

Listing 10a. Retrieve the preloaded pattern - Request

Using the WebSphere CloudBurst REST API interface


© Copyright IBM Corporation 2009. All rights reserved. Page 11 of 18
developerWorks® ibm.com/developerWorks

URL: https://mycloudburst.com:443/resources/patterns/2
HTTP Method: GET
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0

Listing 10b. Retrieve the preloaded pattern - Response

{
"created": 1242965377749,
"currentmessage": null,
"currentmessage_text": null,
"currentstatus": "RM01028",
"currentstatus_text": "Read-only",
"description": "Cluster is a WebSphere Application Server Network Deployment
topology for larger scale development or production environments. The IBM HTTP
Server resides in a dedicated virtual machine (in an unmanaged node).",
"id": 2,
"name": "WebSphere cluster",
"owner": "/resources/users/1",
"properties": {
"part-1.HWAttributes.numvcpus": "1",
"part-1.HWAttributes.memsize": "2048",
"part-1.ConfigWAS.cell_name": "CloudBurstCell",
"part-1.ConfigWAS.node_name": "CloudBurstNode",
"part-1.ConfigWAS.augment_list": "none",
"part-1.ConfigPWD_ROOT.password": null,
"part-1.ConfigPWD_USER.password": null,
"part-2.HWAttributes.numvcpus": "1",
"part-2.HWAttributes.memsize": "2048",
"part-2.ConfigWAS.cell_name": "CloudBurstCell",
"part-2.ConfigWAS.node_name": "CloudBurstNode",
"part-2.ConfigPWD_ROOT.password": null,
"part-2.ConfigPWD_USER.password": null,
"part-3.HWAttributes.numvcpus": "1",
"part-3.HWAttributes.memsize": "2048",
"part-3.ConfigWAS.cell_name": "CloudBurstCell",
"part-3.ConfigWAS.node_name": "CloudBurstNode",
"part-3.ConfigWAS.augment_list": "none",
"part-3.ConfigPWD_ROOT.password": null,
"part-3.ConfigPWD_USER.password": null,
"part-4.HWAttributes.numvcpus": "1",
"part-4.HWAttributes.memsize": "2048",
"part-4.ConfigWAS.cell_name": "CloudBurstCell",
"part-4.ConfigWAS.node_name": "CloudBurstNode",
"part-4.ConfigWAS.augment_list": "none",
"part-4.ConfigPWD_ROOT.password": null,
"part-4.ConfigPWD_USER.password": null,
},
"updated": 1242965394499,
"virtualsystems": [
]
}

The response in Listing 10b depicts the WebSphere Application Server cluster
topology mentioned above:

• The id, name and owner values specify the ID and display name of the

Using the WebSphere CloudBurst REST API interface


Page 12 of 18 © Copyright IBM Corporation 2009. All rights reserved.
ibm.com/developerWorks developerWorks®

pattern, as well as the URI of the user that owns this pattern.
• The properties value specifies a map of part properties and script
parameters for this pattern. Part properties will have keys of the form
part-n.pclass.key and script parameters will have keys of the form
part-n.script-m.key. The values in the returned map will contain
default values for the properties and parameters (or null for properties and
parameters with no defaults).
• The virtualsystems value specifies the list of URIs of the virtual systems
created from this pattern. From the response, you can see that currently
there is no virtual system deployed based on this cluster pattern.
At this point, you have created a private cloud and retrieved a preloaded pattern.
The next section shows how you can use the WebSphere CloudBurst REST API to
deploy patterns into the cloud.

Deploy patterns to the cloud


With a fully initialized private cloud and one or more patterns, you can now deploy
those patterns into your private cloud. Of course, you can use the REST API to do
this as well.

1. When using the REST API to deploy patterns into a private cloud, you will
first create a virtual system resource. In the POST request to create this
resource (Listing 11a) you will indicate the pattern being deployed
(pattern), the cloud that will host the virtual system (cloud), the name of
the virtual system, and other deployment information, such as password
information and WebSphere Application Server configuration data.
Listing 11a. Deploy cluster pattern to the cloud - Request

URL: https://mycloudburst.com:443/resources/virtualSystems
HTTP Method: POST
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"cloud": "/resources/clouds/1",
"name": "Sample Virtual Systems - WebSphere cluster (1Dmgr+2nodes+1IHS)",
"pattern": "/resources/patterns/2",
"properties": {
"*.*.memsize": "1024",
"*.*.password": "password123"
}
}

Using the WebSphere CloudBurst REST API interface


© Copyright IBM Corporation 2009. All rights reserved. Page 13 of 18
developerWorks® ibm.com/developerWorks

Listing 11b. Deploy cluster pattern to the cloud - Response

{
"created": 1242965394588,
"currentmessage": null,
"currentmessage_text": null,
"currentstatus": "RM01036",
"currentstatus_text": "Queued",
"desiredstatus": "",
"desiredstatus_text": null,
"id": 14,
"name": " Sample Virtual Systems - WebSphere cluster (1Dmgr+2nodes+1IHS)",
"owner": "/resources/users/1",
"pattern": "/resources/patterns/2",
"updated": 1242965394588
}

The properties value specifies the part property and script parameter
values (if script packages have been included in the pattern) to be used
for the new virtual system. When a pattern is retrieved, it includes a map
of properties and parameters that must be specified. The map supplied
when creating a virtual system must provide values for any missing
properties and parameters, and can additionally supply values to override
the default values.

In the above example, wildcards were used for supplying property values.
The use of *.* for both the memsize and password parameters means that
those values apply to each part in the pattern. As such, each virtual
machine created during pattern deployment will be allocated 1024 MB of
virtual memory, and the password to each virtual machine will be
password123. (See the WebSphere CloudBurst Information Center for
more information on the use of wildcards when supplying property values
for virtual systems.)

After you make the POST request, log into the WebSphere CloudBurst
admin console to see your deployment (Figure 2).

Figure 2. New deployed virtual system

Using the WebSphere CloudBurst REST API interface


Page 14 of 18 © Copyright IBM Corporation 2009. All rights reserved.
ibm.com/developerWorks developerWorks®

You can see that four virtual machines will be created during the
deployment, one for each of the parts included in the WebSphere
Application Server cluster pattern.

2. After some period of time, a GET request for the virtual system resource
that was created in the POST request will show that all of the virtual
machines have been started, and that the WebSphere Application Server
environment is ready to use. In Listing 12a, you are issuing a GET
request for the virtual system resource with an ID of 14. That ID is used
here because it was returned in the response to the POST request issued
to create the virtual system resource (Listing 12b).
Listing 12a. Query a virtual system - Request

URL: https://mycloudburst.com:443/resources/virtualSystems/14
HTTP Method: GET
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
X-CloudBurst-API-Version: 1.0

Listing 12b. Query a virtual system - Response

{
"desiredstatus_text": null,
"currentstatus_text": "Started",
"created": 1242965394588,
"name": "WebSphere Cluster",
"currentstatus": "RM01006",
"desiredstatus": "",
"currentmessage": "RM07045",
"pattern": "/resources/patterns/2",
"owner": "/resources/users/1",
"updated": 1255027495806,

Using the WebSphere CloudBurst REST API interface


© Copyright IBM Corporation 2009. All rights reserved. Page 15 of 18
developerWorks® ibm.com/developerWorks

"id": 2,
"currentmessage_text": "The virtual system has been deployed and is
ready to use"
}

You can further verify that the virtual system is started by viewing the
virtual system in the WebSphere CloudBurst admin console (Figure 3).

Figure 3. Active virtual system

Summary
The IBM WebSphere CloudBurst Appliance provides three interfaces you can use to
manage and utilize the functions of the appliance. The HTTP REST interface
provides a language-neutral and programming model-agnostic manner with which to
interact with the appliance. This article described how you can use the REST
interface to build a private cloud, customize a WebSphere CloudBurst pattern, and
deploy that pattern to your cloud. Of course, this is just a few of the scenarios in
which the REST interface can be useful. You can explore the full interface and learn
more about how you use it to achieve maximum benefit in the WebSphere
CloudBurst REST API Reference.

Using the WebSphere CloudBurst REST API interface


Page 16 of 18 © Copyright IBM Corporation 2009. All rights reserved.
ibm.com/developerWorks developerWorks®

Resources
Learn
• WebSphere CloudBurst Information Center
• Architectural Styles and the Design of Network-based Software Architectures,
Roy Thomas Fielding, University of California, Irvine, 2000
• WebSphere CloudBurst Appliance Rest API reference
• Videos: WebSphereCloud YouTube channel
• Managing your private cloud, Part 1: Introducing the WebSphere CloudBurst
Appliance command line interface
• Customizing with WebSphere CloudBurst (series)
• Part 1: Creating highly customized private clouds
• Part 2: Using WebSphere CloudBurst to customize a WebSphere
middleware environment

• Cloud computing for the enterprise (series)


• Part 1: Capturing the cloud
• Part 2: WebSphere sMash and DB2 Express-C on the Amazon EC2 public
cloud
• Part 3: Using WebSphere CloudBurst to create private clouds

• WebSphere CloudBurst Appliance product information


• Cloud Computing Journal
• Is there value in cloud computing?
• IBM developerWorks WebSphere
Discuss
• Space: WebSphere Cloud Computing for Developers
• Space: Cloud Computing Central
• YouTube: WebSphere CloudBurst Appliance videos
• Forum: WebSphere CloudBurst Appliance Forum
• Blog: A view from the clouds: Cloud computing for the WebSphere developer
• Follow us on Twitter

Using the WebSphere CloudBurst REST API interface


© Copyright IBM Corporation 2009. All rights reserved. Page 17 of 18
developerWorks® ibm.com/developerWorks

About the authors


Dustin Amrhein
Dustin Amrhein joined IBM as a member of the development team for WebSphere
Application Server. While in that position, Dustin worked primarily on Web services
infrastructure and Web services programming models. In addition, Dustin worked on
the development of a RESTful services framework for Java runtimes. In his current
role, Dustin is a technical evangelist for emerging technologies in IBM’s WebSphere
portfolio.

Xi Ning Wang
Xi Ning Wang is a software engineer in China in the Service-oriented Architecture
(SOA) Design Center. He is on the SOA Advanced Technologies team within the IBM
Software Group, where he develops SOA technology development. Currently, he
focuses on the areas of Web services, modeling- and policy-related technologies.

Using the WebSphere CloudBurst REST API interface


Page 18 of 18 © Copyright IBM Corporation 2009. All rights reserved.

You might also like