IBM Smart Business

Development & Test

on the IBM Cloud

REST API Reference

API version: 20090403
API designation: provisional
Document version: v1.0
Development & Test on the IBM Cloud REST API Guide

Table of contents
1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

3 Request Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

4 Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

5 API Command Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

5.1 Image Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

5.1.1 GET /images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5.1.2 GET /images/$IMAGE_ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5.1.3 DELETE /images/$IMAGE_ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.1.4 PUT /images/$IMAGE_ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.1.4.1 PUT visibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5.2 Instance Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

5.2.1 GET /instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
5.2.2 GET /instances/$INSTANCE_ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.2.3 POST /instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.2.4 DELETE /instances/$INSTANCE_ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.2.5 PUT /instances/$INSTANCE_ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.2.5.1 PUT expirationTime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.2.5.2 PUT state. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.2.6 GET /requests/$REQUEST_ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

5.3 Key Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

5.3.1 GET /keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.3.2 POST /keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.3.3 PUT /keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6 Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
7 Appendix A: XSD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
8 Appendix B: Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
9 Appendix C: States. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
 Development & Test on the IBM Cloud REST API Guide 1

1 Overview
IBM Smart Business Development and Test on the IBM Cloud offers dynamic provision-
ing, scalable runtime environment that supports the end-to-end lifecycle for development
and test activities. Integration within developer tooling is enabled through several appli-
cation programming interfaces. SOAP and REST endpoints have been designed to be
simple and flexible enabling extension and integration. This document reviews the cur-
rent REST API. The SOAP based endpoint will be documented in a future release. Both
the REST and SOAP endpoints should be considered provisional in form and function
and may change without notice.

Who should read this guide

Developers and architects interested in understanding or working programmatically with
the IBM Smart Business Development and Test on the IBM Cloud will find the necessary
details on the current REST API.

This guide presumes knowledge of XML, web services, REST and a programming lan-
guage. Developers should review the IBM Smart Business Development and Test on the
IBM Cloud User Guide (www.ibm.com/cloud/developer/static/userguide.html). Much of
the capabilities exposed through the web experience are available through the API. De-
velopers should explore the web experience to gain a better understanding of the overall
solution.

API Designation
The current application programming interface is officially released as provisional and will
change. This document will be updated and published to coincide with changes to the
API. The goal is to ensure this programming interface evolves to meet the needs of the
development community.

API Versioning
Changes to the REST API are versioned with the date (e.g. 20091101) and is clearly
seen as part of the URL.

Improving the API

The current API is provisional in nature, explicitly noting that it will change. Help influence
the evolution by providing feedback through the online forums or through email.

Feedback specific to this user guide should be sent to: [email protected]

Recent changes
•U
 RLs use to point at www-949.ibm.com. They are now written as www.ibm.com which
is a redirect.
 Development & Test on the IBM Cloud REST API Guide 2

• Additional content was added to this document to describe the additional requirement
that HTTP client code needs to follow redirects.

Upcoming changes
The earliest versions of the API were not intended for public consumption and as such
do not follow the conventions of the provisional designation. In upcoming releases two
things will be apparent:

1. The REST API URLs will contain the word provisional.

2. The XML namespace will include the word provisional.

The private endpoints will be formally deprecated and eventually removed.

This document will track their availability.

2 Security
Currently, the REST-API is a secured web resource which uses Basic Authentication and
SSL. In order to use the API services a user must be registered with the DeveloperCloud
and be able to provide their credentials with each request. All requests to the API are
required to go over SSL to ensure transport level encryption. No message level signing
or encryption is done at this time.

3 Request Structure
The Developer Cloud API follows the REST access pattern applying the HTTP semantics
to its application domain. All DeveloperCloud objects can be accessed and manipulated
via unique URIs that can be built from the base URL using the standard set of HTTP
Methods.

Note: The URLs in this document will redirect to other hosts and as such require your
HTTP client code to follow redirects.

Base URL: https://www.ibm.com/cloud/developer/api/rest/20090403/

Valid Resource Endpoints:

images <Base URL>/images/
instances <Base URL>/instances/
requests <Base URL>/requests/
keys <Base URL>/keys/
 Development & Test on the IBM Cloud REST API Guide 3

Requests use the typical HTTP name/value pair approach for passing parameters.
Message bodies use the typical HTTP body encoding. Specific and valid message
bodies and parameters are used throughout the rest of this guide.

4 Response Format
The DeveloperCloud API is built to support a variety of different response encodings.
The default encoding of responses is XML. The 20090403 version of the API supports
both XML JSON (JavaScript Object Notation) response encodings. Use the AcceptHTTP
header to define the desired response encoding. The table below defines the supported
response encodings and the associated Accept header MIME Type value:

Response Encoding MIME Type

XML text/xml
JSON application/json

HTTP Request:

GET /cloud/developer/api/rest/20090403/images HTTP/1.1

Host: www-949.ibm.com
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.1.1)
Gecko/20090715 Firefox/3.5.1
Accept: application/json
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive: 300
Connection: keep-alive
Cookie: …
Cache-Control: max-age=0

HTTP Response:

HTTP/1.x 200 OK
Date: Fri, 31 Jul 2009 11:45:54 GMT
Server: IBM_HTTP_Server
Cache-Control: max-age=3600
Expires: Fri, 31 Jul 2009 12:48:40 GMT
Vary: Accept-Encoding,User-Agent
Content-Encoding: gzip
Content-Type: application/json
Content-Language: en-US
Transfer-Encoding: chunked
 Development & Test on the IBM Cloud REST API Guide 4

The DeveloperCloud API also has full support for the GZIP Content-Encoding. In order
to have responses compressed using GZIP set the Accept-Encoding header in the HTTP
Request to gzip.

5 API Command Reference

5.1 Image Management

5.1.1 GET /images

Description: Returns the list of Images available to be provisioned on the

IBM DeveloperCloud.

Message Body: None

XML Response:
<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:DescribeImagesResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>

<Image>
<ID>1</ID>
<ProductCodes>
<ProductCode>DC-TP-IMG0011</ProductCode>
</ProductCodes>
<Name>Rational Build Forge</Name>
<State>1</State>
<Owner>SYSTEM</Owner>
<Visibility>PUBLIC</Visibility>
<Description>
 Rational Build Forge provides an adaptive process
execution framework that automates, orchestrates, man-
ages, and tracks all the processes between each handoff
within the assembly line of software development, creat-
ing an automated software factory.
</Description>
<Manifest>file:///META-INF/MANIFEST.MF</Manifest>
<Documentation></Documentation>
</Image>
…
</ns2:DescribeImagesResponse>
Development & Test on the IBM Cloud REST API Guide 5

JSON Response:
{
“images”:[
{
“state”:1,
“visibility”:PUBLIC,
“owner”:”SYSTEM”,
“productCodes”:[
“DC-TP-IMG0011”
],
“documentation”:””,
“name”:”Rational Build Forge”,
“id”:”1”,
“
description”:”Rational Build Forge provides an adap-
tive process execution framework that automates, orches-
trates, manages, and tracks all the processes between
each handoff within the assembly line of software devel-
opment, creating an automated software factory.”,
“manifest”:”file:///META-INF/MANIFEST.MF”
},
…
]
}

Error Codes: None

5.1.2 GET /images/$IMAGE_ID

Description: Returns the available Image identified by the supplied Image ID

Message Body: None

XML Response:
<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:DescribeImageResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>

<Image>
<ID>1</ID>
<ProductCodes>
<ProductCode>DC-TP-IMG0011</ProductCode>
</ProductCodes>
<Name>Rational Build Forge</Name>
<State>1</State>
<Owner>SYSTEM</Owner>
<Visibility>PUBLIC</Visibility>
Development & Test on the IBM Cloud REST API Guide 6

<Description>
 Rational Build Forge provides an adaptive process execu-
tion framework that automates, orchestrates, manages, and
tracks all the processes between each handoff within the
assembly line of software development, creating an auto-
mated software factory.
</Description>
<Manifest>file:///META-INF/MANIFEST.MF</Manifest>
<Documentation></Documentation>
</Image>
</ns2:DescribeImageResponse>

JSON Response:
{
“state”:1,
“visibility”:”PUBLIC”,
“owner”:”SYSTEM”,
“productCodes”:[
“DC-TP-IMG0011”
],
“documentation”:””,
“name”:”Rational Build Forge”,
“id”:”1”,
“description”:”Rational Build Forge provides an adaptive process
execution framework that automates, orchestrates, manages,
and tracks all the processes between each handoff within the
assembly line of software development, creating an automated
software factory.”,
“manifest”:”file:///META-INF/MANIFEST.MF”
}

Error Codes:
404: The image specified by the supplied $IMAGE_ID is not found

5.1.3 DELETE /images/$IMAGE_ID

Description: Deletes Image identified by the supplied Image ID.

Message Body: None

XML Response:
<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:DeleteImageResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>
</ns2:DeleteImageResponse>
Development & Test on the IBM Cloud REST API Guide 7

JSON Response:
{ “success”:true }

Error Codes:
401: The user is not authorized to delete this image
404: The image specified by the supplied $IMAGE_ID is not found
412: The image is in an invalid state to perform this operation
500: An unknown error occurred deleting this image

5.1.4 PUT /images/$IMAGE_ID

5.1.4.1 PUT visibility

Description: Makes the Image identified by the supplied Image ID publically avail-
able for all users to create Instances of.

Message Body:
visibility: The new visibility state of the image, currently only PUBLIC is supported.

XML Response:
<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:PromoteImageResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>
<Image>
<ID>1</ID>
<ProductCodes>
<ProductCode>DC-TP-IMG0011</ProductCode>
</ProductCodes>
<Name>Rational Build Forge</Name>
<State>1</State>
<Owner>SYSTEM</Owner>
<Visibility>PUBLIC</Visibility>
<Description>
 Rational Build Forge provides an adaptive process
execution framework that automates, orchestrates,
manages, and tracks all the processes between each
handoff within the assembly line of software devel-
opment, creating an automated software factory.
</Description>
<Manifest>file:///META-INF/MANIFEST.MF</Manifest>
<Documentation></Documentation>
</Image>
</ns2:PromoteImageResponse>
 Development & Test on the IBM Cloud REST API Guide 8

JSON Response:
{
“state”:1,
“visibility”:”PUBLIC”,
“owner”:”SYSTEM”,
“productCodes”:[
“DC-TP-IMG0011”
],
“documentation”:””,
“name”:”Rational Build Forge”,
“id”:”1”,
“
description”:”Rational Build Forge provides an adaptive pro-
cess execution framework that automates, orchestrates, man-
ages, and tracks all the processes between each handoff within
the assembly line of software development, creating an auto-
mated software factory.”,
“manifest”:”file:///META-INF/MANIFEST.MF”
}

Error Codes:
401: The user is not authorized to change the visibility of this image
404: The image specified by the supplied $IMAGE_ID is not found
412: The image is in an invalid state to perform this operation
500: An unknown error occurred deleting this image

5.2 Instance Management

5.2.1 GET /instances

Description: Returns the list of Instances that the authenticated user manages.

Message Body: None

XML Response:
<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:DescribeInstancesResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>
<Instance>
<ID>3608:180889</ID>
<RequestID name=”Testing”>3608</RequestID>
<Owner>[email protected]</Owner>
<Hostname>vm064.developer.ihost.com</Hostname>
<IP>129.33.194.74</IP>
<ImageID>3</ImageID>
<Status>5</Status>
<LaunchTime>2009-07-27T00:00:00.000-04:00</LaunchTime>
Development & Test on the IBM Cloud REST API Guide 9

<ExpirationTime>2009-08-10T00:00:00.000-04:00</ExpirationTime>
<ProductCodes/>
<Software>
<Application>
<Name>SLES</Name>
<Version>10 SP2</Version>
<Type>OS</Type>
</Application>
</Software>
</Instance>
…
</ns2:DescribeInstancesResponse>

JSON Response:
{
“instances”:[
{
“launchTime”:1248667200000,
“status”:5,
“hostname”:”vm064.developer.ihost.com”,
“owner”:”[email protected]”,
“imageId”:”3”,
“software”:[
{
“version”:”10 SP2”,
“type”:”OS”,
“name”:”SLES”
}
],
“productCodes”:[],
“ip”:”129.33.194.74”,
“requestName”:”Testing”,
“requestId”:”3608”,
“id”:”3608:180889”,
“expirationTime”:1249876800000
},
…
]
}

Error Codes:
401: The currently authenticated user is not authorized to view
this information
500: An unexpected error occurred getting the list of instances for the
authenticated user
Development & Test on the IBM Cloud REST API Guide 10

5.2.2 GET /instances/$INSTANCE_ID

Description: Returns the Instance that the authenticated user manages with the
specified $INSTANCE_ID.

Message Body: None

XML Response:
<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:DescribeInstanceResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>
<Instance>
<ID>3608:180889</ID>
<RequestID name=”Testing”>3608</RequestID>
<Owner>[email protected]</Owner>
<Hostname>vm064.developer.ihost.com</Hostname>
<IP>129.33.194.74</IP>
<ImageID>3</ImageID>
<Status>5</Status>
<LaunchTime>2009-07-27T00:00:00.000-04:00</LaunchTime>
<ExpirationTime>2009-08-10T00:00:00.000-04:00</ExpirationTime>
<ProductCodes/>
<Software>
<Application>
<Name>SLES</Name>
<Version>10 SP2</Version>
<Type>OS</Type>
</Application>
</Software>
</Instance>
</ns2:DescribeInstanceResponse>

JSON Response:
{
“launchTime”:1248667200000,
“status”:5,
“hostname”:”vm064.developer.ihost.com”,
“owner”:”[email protected]”,
“imageId”:”3”,
“software”:[
{
“version”:”10 SP2”,
“type”:”OS”,
“name”:”SLES”
}
],
Development & Test on the IBM Cloud REST API Guide 11

“productCodes”:[],
“ip”:”129.33.194.74”,
“requestName”:”Testing”,
“requestId”:”3608”,
“id”:”3608:180889”,
“expirationTime”:1249876800000
}

Error Codes:
401: The currently authenticated user is not authorized to view this instance
404: The instance specified by the supplied $INSTANCE_ID is not found
500: An unexpected error occurred getting the list of instances for the
authenticated user

5.2.3 POST /instances

Description: Requests a new Instance to be created.

Message Body:
name: The alias to use to reference this instance
imageID: The ID of the image to create this instance from
instanceType: The instance type to use for this instance {SMALL,
MEDIUM, LARGE}
publicKey: The public key to use for accessing the created instance
Configuration Data: Arbitrary name/value pairs defined by the image being created

XML Response:
<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:CreateInstanceResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>
<Instance>
<ID></ID>
<RequestID name=”$name”>xxxx</RequestID>
<Owner>[email protected]</Owner>
<Hostname></Hostname>
<IP></IP>
<ImageID>$imageID</ImageID>
<Status>0</Status>
<LaunchTime>2009-07-27T00:00:00.000-04:00</LaunchTime>
<ExpirationTime>2009-08-10T00:00:00.000-04:00</ExpirationTime>
<ProductCodes/>
<Software>
<Application>
Development & Test on the IBM Cloud REST API Guide 12

<Name>SLES</Name>
<Version>10 SP2</Version>
<Type>OS</Type>
</Application>
</Software>
</Instance>
</ns2:CreateInstanceResponse>

JSON Response:
{
“launchTime”:1248667200000,
“status”:0,
“hostname”:null,
“owner”:”[email protected]”,
“imageId”:$imageID,
“software”:[
{
“version”:”10 SP2”,
“type”:”OS”,
“name”:”SLES”
}
],
“productCodes”:[],
“ip”:null,
“requestName”:$requestName,
“requestId”:”xxxx”,
“id”:null,
“expirationTime”:1249876800000
}

Error Codes:
401: The authenticated user is not authorized to create instances
402: Payment is required before more instances may be created
409: There are not enough resources in the cloud to fulfill this request
412: One or more of the supplied parameters are invalid for this instance
500: An unexpected error occurred creating this instance

5.2.4 DELETE /instances/$INSTANCE_ID

Description: Deletes the Instance that the authenticated user manages with the speci-
fied $INSTANCE_ID.

Message Body: None

Development & Test on the IBM Cloud REST API Guide 13

XML Response:
<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:DeleteInstanceResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>
</ns2:DeleteInstanceResponse>

JSON Response:
{ “success”:true }

Error Codes:
401: The user is not authorized to delete this instance
404: The instance specified by $INSTANCE_ID was not found
412: The instance is in an invalid state to perform this operation
500: An unknown error occurred deleting this instance

5.2.5 PUT /instances/$INSTANCE_ID

5.2.5.1 PUT expirationTime

Description: Sets the expiration time of the instance to the value specified in the
message body

Message Body:
expirationTime: The new expiration time for this instance in milliseconds (epoch)

XML Response:
<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:ExtendReservationResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>
<NewEndDate>2009-08-10T00:00:00.000-04:00</NewEndDate>
</ns2:ExtendReservationResponse>

JSON Response:
{ “expirationTime”:1249876800000 }

Error Codes:
401: The user is not authorized to extend the expiration time of this instance
402: Payment is required before more instances may be created
404: The instance specified by $INSTANCE_ID was not found
406: The provided expiration date is not valid
409: There are not enough resources in the cloud to fulfill this request
412: The instance is in an invalid state to perform this operation
500: An unknown error occurred deleting this instance
Development & Test on the IBM Cloud REST API Guide 14

5.2.5.2 PUT state

Description: Sets the state of the instance to the value specified in the
message body

Message Body:
state: The new state of the instance, valid values are restart, save

When state = restart the additional parameter is optional:

propagateKey: Push the current users default key into the instance during restart.

When state = save the additional parameters are required:

name: The name to associate with the captured image.
description: The description to associate with the capture image.

XML Response:
When a restart request is made:
<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:RestartInstanceResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>
</ns2:RestartInstanceResponse>

When a save request is made:

<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:SaveInstanceResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>
</ns2:SaveInstanceResponse>

JSON Response:
{ “success”:true }

Error Codes:
401: The user is not authorized to perform this action
402: Payment is required before more instances may be created
404: The instance specified by $INSTANCE_ID was not found
409: There are not enough resources in the cloud to fulfill this request
412: The instance is in an invalid state to perform this operation
500: An unknown error occurred deleting this instance

5.2.6 GET /requests/$REQUEST_ID

Description: Returns the list of Instances that the authenticated user manages that
were created as part of the request specified by $REQUEST_ID.
Development & Test on the IBM Cloud REST API Guide 15

Message Body: None

XML Response:
<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:DescribeRequestResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>
<Instance>
<ID>3608:180889</ID>
<RequestID name=”Testing”>3608</RequestID>
<Hostname>vm064.developer.ihost.com</Hostname>
<IP>129.33.194.74</IP>
<ImageID>3</ImageID>
<Status>5</Status>
<LaunchTime>2009-07-27T00:00:00.000-04:00</LaunchTime>
<ExpirationTime>2009-08-10T00:00:00.000-04:00</ExpirationTime>
<ProductCodes/>
<Software>
<Application>
<Name>SLES</Name>
<Version>10 SP2</Version>
<Type>OS</Type>
</Application>
</Software>
</Instance>
…
</ns2:DescribeRequestResponse>

JSON Response:
{
“instances”:[
{
“launchTime”:1248667200000,
“status”:5,
“hostname”:”vm064.developer.ihost.com”,
“owner”:”[email protected]”,
“imageId”:”3”,
“software”:[
{
“version”:”10 SP2”,
“type”:”OS”,
“name”:”SLES”
}
],
“productCodes”:[],
“ip”:”129.33.194.74”,
 Development & Test on the IBM Cloud REST API Guide 16

“requestName”:”Testing”,
“requestId”:”3608”,
“id”:”3608:180889”,
“expirationTime”:1249876800000
},
…
]
}

Error Codes:
401: The currently authenticated user is not authorized to view this request
404: The request specified by the supplied $REQUEST_ID is not found
500: An unexpected error occurred getting the list of instances in this request for the
authenticated user

5.3 Key Management

5.3.1 GET /keys

Description: Used to retrieve the Public Key stored for the authenticated user.

Message Body: None

XML Response:
<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:GetPublicKeyResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>
<PublicKey>
AAAAB3NzaC1yc2EAAAADAQABAAABAQCPxrAmdy01mfChpmEIqyzqxVb8…
</PublicKey>
</ns2:GetPublicKeyResponse>

JSON Response:
{ “publicKey”:”AAAAB3NzaC1yc2EAAAADAQABAAABAQCPxrAmdy01mfChpmEIqyzqx
Vb8…” }

Error Codes: None

5.3.2 POST /keys

Description: Used to generate a new SSH Key Pair for the authenticated user.

Message Body: None

 Development & Test on the IBM Cloud REST API Guide 17

XML Response:
<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:GenerateKeyPairResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>
<PrivateKey>
-----BEGIN RSA PRIVATE KEY-----
 MIIEowIBAAKCAQEAs5ZBc+dWakadPaW6JbTZmWzCPx/PMsAJ7A2nLFy1O8P-
9bNWKCFefRZy0y0KAWoVpWgdx0+QQ2yVIvaEgjJ0KGiBELLc9Hnd0jpMFhFDbIS
sqmWbf
…
-----END RSA PRIVATE KEY-----
</PrivateKey>
</ns2:GenerateKeyPairResponse >

JSON Response:
{ “privateKey”:”
-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAs5ZBc+dWakadPaW6JbTZmWzCPx/PMsAJ7A2nLFy1O8P9bNWK
CFefRZy0y0KAWoVpWgdx0+QQ2yVIvaEgjJ0KGiBELLc9Hnd0jpMFhFDbISsqmWbf
…
-----END RSA PRIVATE KEY-----
“}

Error Codes:
500: An unexpected error occurred generating the new key pair

5.3.3 PUT /keys

Description: Used to update the Public Key stored for the authenticated user.

Message Body:
publicKey: The public key to store

XML Response:
<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?>
<ns2:SetPublicKeyResponse
xmlns:ns2=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”>
</ns2:SetPublicKeyResponse>

JSON Response:
{ “success”:true }
 Development & Test on the IBM Cloud REST API Guide 18

Error Codes:
412: The supplied public key is invalid
500: An unexpected error occurred generating the new key pair

6 Additional resources
Official cloud portal: www.ibm.com/cloud

IBM Smart Business Development & Test on the IBM Cloud:

www.ibm.com/cloud/developer

User Guide - IBM Smart Business Development & Test on the IBM Cloud:
www.ibm.com/cloud/developer/static/userguide.html

7 Appendix A: XSD
<xsd:schema targetNamespace=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-
04-03”
xmlns:tns=”http://www.ibm.com/xmlns/b2b/cloud/api/2009-04-03”
xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
xmlns:ref=”http://ws-i.org/profiles/basic/1.1/xsd”>

<
xsd:import namespace=”http://ws-i.org/profiles/basic/1.1/xsd” schema-
Location=”./WS-ISwA.xsd”/>

<
xsd:element name=”DescribeConfiguration” type=”tns:DescribeConfiguratio
nType” />
<xsd:complexType name=”DescribeConfigurationType”>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”DescribeConfigurationResponse” type=”tns:DescribeConf
igurationResponseType” />
<xsd:complexType name=”DescribeConfigurationResponseType”>
<xsd:sequence>
<xsd:element name=”Configuration” type=”tns:Configuration”/>
</xsd:sequence>
</xsd:complexType>

<xsd:element name=”DescribeInstances” type=”tns:DescribeInstancesType”

 Development & Test on the IBM Cloud REST API Guide 19

nillable=”false” />
<xsd:complexType name=”DescribeInstancesType”>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”DescribeInstancesResponse” type=”tns:DescribeInstan
cesResponseType”
nillable=”false” />
<xsd:complexType name=”DescribeInstancesResponseType”>
<xsd:sequence>
<xsd:element name=”Instance” type=”tns:Instance”
minOccurs=”0” maxOccurs=”unbounded” />
</xsd:sequence>
</xsd:complexType>

<xsd:element name=”DescribeInstance” type=”tns:DescribeInstanceType”

nillable=”false” />
<xsd:complexType name=”DescribeInstanceType”>
<xsd:sequence>
<xsd:element name=”ID” type=”xsd:string” minOccurs=”1”
maxOccurs=”1” nillable=”false” />
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”DescribeInstanceResponse” type=”tns:DescribeInstanc
eResponseType”
nillable=”false” />
<xsd:complexType name=”DescribeInstanceResponseType”>
<xsd:sequence>
<xsd:element name=”Instance” type=”tns:Instance” />
</xsd:sequence>
</xsd:complexType>

<xsd:element name=”DescribeRequest” type=”tns:DescribeRequestType”
nillable=”false” />
<xsd:complexType name=”DescribeRequestType”>
<xsd:sequence>
<xsd:element name=”ID” type=”xsd:string” minOccurs=”1”
maxOccurs=”1” nillable=”false” />
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”DescribeRequestResponse” type=”tns:DescribeRequestR
esponseType”
nillable=”false” />
 Development & Test on the IBM Cloud REST API Guide 20

<xsd:complexType name=”DescribeRequestResponseType”>
<xsd:sequence>
<
xsd:element name=”Instance” type=”tns:Instance” minOccurs=”0”
maxOccurs=”unbounded” />
</xsd:sequence>
</xsd:complexType>

<xsd:element name=”CreateInstance” type=”tns:CreateInstanceType”

nillable=”false” />
<xsd:complexType name=”CreateInstanceType”>
<xsd:sequence>
<xsd:element name=”Name” type=”xsd:string” />
<xsd:element name=”ImageID” type=”xsd:string” />
<xsd:element name=”InstanceType” type=”xsd:string” />
<xsd:element name=”PublicKey” type=”xsd:string” />
<xsd:element name=”Quantity” type=”xsd:int” />
<xsd:element name=”Configuration” type=”tns:Configuration” />
<xsd:element name=”Files” type=”tns:Files” />
</xsd:sequence>
</xsd:complexType>

<xsd:complexType name=”Files”>
<xsd:sequence>
<
xsd:element name=”File” minOccurs=”0” maxOccurs=”unbounded”
type=”ref:swaRef” />
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”CreateInstanceResponse” type=”tns:CreateInstanceRes
ponseType”
nillable=”false” />
<xsd:complexType name=”CreateInstanceResponseType”>
<xsd:sequence>
<
xsd:element name=”Instance” type=”tns:Instance”
maxOccurs=”unbounded” />
</xsd:sequence>
</xsd:complexType>

<xsd:element name=”DeleteInstance” type=”tns:DeleteInstanceType”
nillable=”false” />
<xsd:complexType name=”DeleteInstanceType”>
<xsd:sequence>
<xsd:element name=”ID” type=”xsd:string” minOccurs=”1”
maxOccurs=”1” nillable=”false” />
</xsd:sequence>
</xsd:complexType>
 Development & Test on the IBM Cloud REST API Guide 21

<
xsd:element name=”DeleteInstanceResponse” type=”tns:DeleteInstanceRes
ponseType”
nillable=”false” />
<xsd:complexType name=”DeleteInstanceResponseType”>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”SaveInstance” type=”tns:SaveInstanceType”
nillable=”false” />
<xsd:complexType name=”SaveInstanceType”>
<xsd:sequence>
<xsd:element name=”ID” type=”xsd:string” />
<xsd:element name=”Name” type=”xsd:string” />
<xsd:element name=”Description” type=”xsd:string” />
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”SaveInstanceResponse” type=”tns:SaveInstanceRespons
eType” nillable=”false” />
<xsd:complexType name=”SaveInstanceResponseType”>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>

<xsd:element name=”StartInstance” type=”tns:StartInstanceType”

nillable=”false” />
<xsd:complexType name=”StartInstanceType”>
<xsd:sequence>
<xsd:element name=”ID” type=”xsd:string” minOccurs=”1”
maxOccurs=”1” nillable=”false” />
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”StartInstanceResponse” type=”tns:StartInstanceRespo
nseType”
nillable=”false” />
<xsd:complexType name=”StartInstanceResponseType”>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>

<xsd:element name=”StopInstance” type=”tns:StopInstanceType”

nillable=”false” />
<xsd:complexType name=”StopInstanceType”>
 Development & Test on the IBM Cloud REST API Guide 22

<xsd:sequence>
<xsd:element name=”ID” type=”xsd:string” minOccurs=”1”
maxOccurs=”1” nillable=”false” />
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”StopInstanceResponse” type=”tns:StopInstanceRespons
eType”
nillable=”false” />
<xsd:complexType name=”StopInstanceResponseType”>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>

<xsd:element name=”RestartInstance” type=”tns:RestartInstanceType”

nillable=”false” />
<xsd:complexType name=”RestartInstanceType”>
<xsd:sequence>
<xsd:element name=”ID” type=”xsd:string” minOccurs=”1”
maxOccurs=”1” nillable=”false” />
<xsd:element name=”PropagateKey” type=”xsd:boolean” />
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”RestartInstanceResponse” type=”tns:RestartInstanceR
esponseType”
nillable=”false” />
<xsd:complexType name=”RestartInstanceResponseType”>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”ExtendReservation” type=”tns:ExtendReservationType”
nillable=”false” />
<xsd:complexType name=”ExtendReservationType”>
<xsd:sequence>
<xsd:element name=”ID” type=”xsd:string” />
<xsd:element name=”EndDate” type=”xsd:dateTime” />
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”ExtendReservationResponse” type=”tns:ExtendReservat
ionResponseType” nillable=”false” />
<xsd:complexType name=”ExtendReservationResponseType”>
<xsd:sequence>
<xsd:element name=”NewEndDate” type=”xsd:dateTime” />
 Development & Test on the IBM Cloud REST API Guide 23

</xsd:sequence>
</xsd:complexType>

<xsd:element name=”DescribeImages” type=”tns:DescribeImagesType” />

<xsd:complexType name=”DescribeImagesType”>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”DescribeImagesResponse” type=”tns:DescribeImagesRes
ponseType” />
<xsd:complexType name=”DescribeImagesResponseType”>
<xsd:sequence>
<xsd:element name=”Image” type=”tns:Image” minOccurs=”0”
maxOccurs=”unbounded” />
</xsd:sequence>
</xsd:complexType>

<xsd:element name=”DescribeImage” type=”tns:DescribeImageType” />
<xsd:complexType name=”DescribeImageType”>
<xsd:sequence>
<xsd:element name=”ImageID” type=”xsd:string” />
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”DescribeImageResponse” type=”tns:DescribeImageRespo
nseType” />
<xsd:complexType name=”DescribeImageResponseType”>
<xsd:sequence>
<xsd:element name=”Image” type=”tns:Image” />
</xsd:sequence>
</xsd:complexType>

<xsd:element name=”DeleteImage” type=”tns:DeleteImageType” />
<xsd:complexType name=”DeleteImageType”>
<xsd:sequence>
<xsd:element name=”ImageID” type=”xsd:string” />
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”DeleteImageResponse” type=”tns:DeleteImageResponseT
ype” />
<xsd:complexType name=”DeleteImageResponseType”>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>
 Development & Test on the IBM Cloud REST API Guide 24

<xsd:element name=”PromoteImage” type=”tns:PromoteImageType” />
<xsd:complexType name=”PromoteImageType”>
<xsd:sequence>
<xsd:element name=”ImageID” type=”xsd:string” />
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”PromoteImageResponse” type=”tns:PromoteImageRespons
eType” />
<xsd:complexType name=”PromoteImageResponseType”>
<xsd:sequence>
<xsd:element name=”Image” type=”tns:Image” />
</xsd:sequence>
</xsd:complexType>

<xsd:element name=”GetPublicKey” type=”tns:GetPublicKeyType” />

<xsd:complexType name=”GetPublicKeyType”>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”GetPublicKeyResponse” type=”tns:GetPublicKeyRespons
eType” />
<xsd:complexType name=”GetPublicKeyResponseType”>
<xsd:sequence>
<xsd:element name=”PublicKey” type=”xsd:string” />
</xsd:sequence>
</xsd:complexType>

<xsd:element name=”SetPublicKey” type=”tns:SetPublicKeyType” />

<xsd:complexType name=”SetPublicKeyType”>
<xsd:sequence>
<xsd:element name=”PublicKey” type=”xsd:string” />
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”SetPublicKeyResponse” type=”tns:SetPublicKeyRespons
eType” />
<xsd:complexType name=”SetPublicKeyResponseType”>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>

<xsd:element name=”GenerateKeyPair” type=”tns:GenerateKeyPairType” />
<xsd:complexType name=”GenerateKeyPairType”>
 Development & Test on the IBM Cloud REST API Guide 25

<xsd:sequence>
</xsd:sequence>
</xsd:complexType>

<
xsd:element name=”GenerateKeyPairResponse” type=”tns:GenerateKeyPairR
esponseType” />
<xsd:complexType name=”GenerateKeyPairResponseType”>
<xsd:sequence>
<xsd:element name=”PrivateKey” type=”xsd:string” />
</xsd:sequence>
</xsd:complexType>

<xsd:complexType name=”Image”>
<xsd:sequence>
<xsd:element name=”ID” type=”xsd:string” />
<xsd:element name=”ProductCodes” type=”tns:ProductCodes” />
<xsd:element name=”Name” type=”xsd:string” />
<xsd:element name=”Location” type=”xsd:string” />
<xsd:element name=”State” type=”xsd:integer” />
<xsd:element name=”Owner” type=”xsd:string” />
<xsd:element name=”Visibility” type=”tns:VisibilityType” />
<xsd:element name=”Architecture” type=”xsd:string” />
<xsd:element name=”Platform” type=”xsd:string” />
<xsd:element name=”Description” type=”xsd:string” />
<xsd:element name=”Manifest” type=”xsd:string” />
<xsd:element name=”Documentation” type=”xsd:string” />
<
xsd:element name=”SupportedInstanceTypes” type=”tns:SupportedI
nstanceTypes” />
</xsd:sequence>
</xsd:complexType>

<xsd:complexType name=”SupportedInstanceTypes”>
<xsd:sequence>
<
xsd:element name=”InstanceType” type=”xsd:string”
maxOccurs=”unbounded”/>
</xsd:sequence>
</xsd:complexType>

<xsd:simpleType name=”VisibilityType”>
<xsd:restriction base=”xsd:string”>
<xsd:enumeration value=”PUBLIC” />
<xsd:enumeration value=”SHARED” />
<xsd:enumeration value=”PRIVATE” />
</xsd:restriction>
</xsd:simpleType>
 Development & Test on the IBM Cloud REST API Guide 26

<xsd:complexType name=”Instance”>
<xsd:sequence>
<xsd:element name=”ID” type=”xsd:string” />
<xsd:element name=”Name” type=”xsd:string” />
<xsd:element name=”RequestID” type=”tns:Request” />
<xsd:element name=”Owner” type=”xsd:string” />
<xsd:element name=”Hostname” type=”xsd:string” />
<xsd:element name=”IP” type=”xsd:string” />
<xsd:element name=”ImageID” type=”xsd:string” />
<xsd:element name=”InstanceType” type=”xsd:string” />
<xsd:element name=”Status” type=”xsd:integer” />
<xsd:element name=”KeyName” type=”xsd:string” />
<xsd:element name=”LaunchTime” type=”xsd:dateTime” />
<xsd:element name=”ExpirationTime” type=”xsd:dateTime” />
<xsd:element name=”ProductCodes” type=”tns:ProductCodes” />
<xsd:element name=”Software”>
<xsd:complexType>
<xsd:sequence>
<
xsd:element name=”Application”
type=”tns:Application” minOccurs=”0”
maxOccurs=”unbounded” />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>

<xsd:complexType name=”Request”>
<xsd:simpleContent>
<xsd:extension base=”xsd:string”>
<
xsd:attribute name=”name” type=”xsd:string”
use=”optional” />
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>

<xsd:complexType name=”ProductCodes”>
<xsd:sequence>
<
xsd:element name=”ProductCode” type=”xsd:string”
maxOccurs=”unbounded”/>
</xsd:sequence>
</xsd:complexType>

<xsd:complexType name=”Application”>
<xsd:sequence>
<xsd:element name=”Name” type=”xsd:string”/>
<xsd:element name=”Version” type=”xsd:string”/>
<xsd:element name=”Type” type=”xsd:string”/>
 Development & Test on the IBM Cloud REST API Guide 27

</xsd:sequence>
</xsd:complexType>

<xsd:complexType name=”Configuration”>
<xsd:sequence>
<xsd:element name=”Property” type=”tns:NameValuePair”
minOccurs=”0” maxOccurs=”unbounded” />
</xsd:sequence>
</xsd:complexType>

<xsd:complexType name=”NameValuePair”>
<xsd:sequence>
<xsd:element name=”Name” type=”xsd:string” />
<xsd:element name=”Value” type=”xsd:string” />
</xsd:sequence>
</xsd:complexType>

<xsd:complexType name=”Fault”>
<xsd:sequence>
<xsd:element name=”Timestamp” type=”xsd:dateTime” />
<xsd:element name=”Description” type=”xsd:string” />
<xsd:element name=”Cause” type=”xsd:string” />
<xsd:element name=”Code” type=”xsd:integer” />
</xsd:sequence>
</xsd:complexType>

<xsd:element name=”UnknownAccountFault” type=”tns:Fault” />

<xsd:element name=”PublicKeyUpdateFailedFault” type=”tns:Fault” />
<xsd:element name=”InvalidPublicKeyFault” type=”tns:Fault” />
<xsd:element name=”KeyGenerationFailedFault” type=”tns:Fault” />
<xsd:element name=”UnknownInstanceFault” type=”tns:Fault” />
<xsd:element name=”UnknownImageFault” type=”tns:Fault” />
<xsd:element name=”UnknownRequestFault” type=”tns:Fault” />
<xsd:element name=”UnauthorizedUserFault” type=”tns:Fault” />
<xsd:element name=”InsufficientResourcesFault” type=”tns:Fault” />
<xsd:element name=”InvalidConfigurationFault” type=”tns:Fault” />
<xsd:element name=”InvalidReservationDateFault” type=”tns:Fault” />
<xsd:element name=”PaymentRequiredFault” type=”tns:Fault” />
<xsd:element name=”InvalidStateFault” type=”tns:Fault” />
<xsd:element name=”UnknownErrorFault” type=”tns:Fault” />
</xsd:schema>
 Development & Test on the IBM Cloud REST API Guide 28

8 Appendix B: Status
Value Name
0 NEW
1 PROVISIONING
2 FAILED
3 REMOVED
4 REJECTED
5 ACTIVE
6 UNKNOWN
7 DEPROVISIONING
8 RESTARTING
9 STARTING
10 STOPPING
11 STOPPED

9 Appendix C: States
Value Name
0 NEW
1 AVAILABLE
2 UNAVAILABLE
3 DELETED
4 CAPTURING
©Copyright IBM Corporation 2009

Cloud Computing Enablement, Enterprise Initiatives

Route 100, Somers, NY 10589 U.S.A.

Printed in the United States of America 2009. All Rights Reserved

IBM, the IBM logo, the e-business logo are trademarks or registered trademarks of International Business Machines
Corporation in the United States, other countries, or both
.
Other company, product and service names may be trademarks or service marks of others.

References in this publication to IBM products or services do not imply that IBM intends to make them available in all countries in
which IBM operates.