Call IBM SmartCloud Enterprise+ services programmatically

An overview of APIs that support managed cloud services

This article shows administrative users of IBM® SmartCloud® Enterprise+ Version 1.2 how to perform basic management tasks by means of SmartCloud Enterprise+ APIs. Command examples demonstrate use of the APIs for inspecting metadata and resources, managing administrative resources, and managing virtual servers.

Andrew Hoppe (hoppea@us.ibm.com), Senior Software Engineer, IBM

Andrew Hoppe, Ph.D., came to IBM in 2003 with the Rational acquisition. He has 20 years of software modeling, design and development experience. In 2013, he joined the IBM Global Technology Services (GTS) Global Cloud Ecosystem team as a technical architect.



Jeff Klink, Senior Technical Staff Member, IBM

Jeff Klink is a senior technical staff member (STSM) with IBM Canada. For the past 10 years, Jeff has focused on virtualization, appliances, networking, and backup technologies with a primary focus on Linux-based technologies and designs. Currently, Jeff serves as the worldwide lead for the IBM Global Technology Services (GTS) Global Cloud Ecosystem technical team, which enables IBM x86 and Power series SaaS vendors to architect and build their solutions on SoftLayer and IBM SmartCloud Enterprise+ public clouds.



12 November 2013

Also available in Chinese Russian Japanese

IBM SmartCloud Enterprise+

SmartCloud Enterprise+, one of the IBM cloud computing offerings, provides an enterprise-class Infrastructure as a Service (IaaS) environment. IBM administers and fully manages SmartCloud Enterprise+ using automated tooling, including Tivoli® automation and monitoring tools. Its strong security, reliability, and performance characteristics make SmartCloud Enterprise+ an ideal candidate for hosting cloud-enabled legacy production workloads in eight IBM global data centers.

Users of IBM SmartCloud Enterprise+ can create and administer virtual assets through an integrated service management (ISM) based web portal. Most of the portal capabilities are also available through APIs. By using the APIs, you can control creation and maintenance of SmartCloud Enterprise+ resources from a program. Therefore, the APIs can be used to automatically provision, scale, and reconfigure SmartCloud Enterprise+ deployments.

SmartCloud Enterprise+ APIs are implemented as Representational State Transfer (REST) calls that are available at a predefined endpoint URL. (The endpoint URL is communicated to IBM customers during SmartCloud Enterprise+ onboarding, so this article's examples use an endpoint_URL placeholder instead of actual endpoint URLs.) The APIs provide three main capabilities:

  • Read-only inspection of SmartCloud Enterprise+ metadata and resources
  • Management of administrative resources (users, teams, projects, and approvals)
  • Management of SmartCloud Enterprise+ virtual servers, patches, and snapshots

In this article, we discuss and provide examples of API usage in all three categories. Our code samples use the cURL command-line utility, which enables you to use simple HTTP commands to transfer data. We also illustrate REST call parameters in each cURL call.

Call syntax

SmartCloud Enterprise+ REST API requests can pass call parameters in both the HTTP request header and body. For request-passing parameters in the message body, the Content-Type header element, with a value of either application/xml or application/json, is required. Depending on content type, in the request body you should place either an XML or JavaScript Object Notation (JSON) element containing all attributes of the resource being created. You can also use the Accept header to specify the requested format of the response (also application/xml or application/json).

REST queries (HTTP GET requests) that return a collection of elements can have additional URL parameters that specify filtering criteria for the query (for example, GET baseURL/users?first_name=John). Also, GET queries can request results to be sorted or truncated. For details, see the IBM SmartCloud Enterprise+ API Specifications document, which you can obtain during SmartCloud Enterprise+ onboarding.


Viewing, creating, and maintaining SmartCloud Enterprise+ projects and server instances

Next, we'll show you how to use the APIs for programmatic control of viewing, creating, and maintaining SmartCloud Enterprise+ projects and server instances.

Retrieve resource metadata

Figure 1 is a diagram of the SmartCloud Enterprise+ resource model:

Figure 1. SmartCloud Enterprise+ resource model
Illustration of the IBM SmartCloud Enterprise+ resource model

In Figure 1, arrows indicate dependencies between resources or references from one resource to another. From the model, you can see which kinds of resources are needed for an instance (SmartCloud Enterprise+ server) to be created. Instances are tied to groups. A group is an abstract grouping of resources, for which the only physical realization in SmartCloud Enterprise+ is a project. Projects are, in turn, composed of teams containing users. Teams, users, and groups must be created before instances can be associated with them.

Note: In all of the command examples, bold-italic font indicates (by example) information that the issuing user must supply in addition to the endpoint URL. Also, some cURL code samples in the article include line breaks for readability; remove the line breaks before running the commands.

Furthermore, users and instances must be associated with a number of existing SmartCloud Enterprise+ resources, so you must extract metadata for those resources. For example, a user requires a role, which is a unique SmartCloud Enterprise+ resource.

A SmartCloud Enterprise+ user can have up to two roles. To retrieve a user's role metadata, issue the REST GET command:

curl -k -X GET -u johntester@test.com:johnspasswd https://endpoint_URL/roles

An example response to the preceding command is:

<roles>
  <role>
    <id>53</id>
    <name>Administrator</name>
    <role_group>IaaS-User</role_group>
  </role>
  <role>
    <id>54</id>
    <name>Business Manager</name>
    <role_group>IaaS-User</role_group>
  </role>
</roles>

You can also issue the REST GET command in a browser, because browsers issue HTTP GET requests by default. Type in the REST call URL:

https://endpoint_URL/roles

The browser then displays the default XML-formatted response.

Create users

To create a user, you must specify:

  • User ID (the user's email address)
  • Display name
  • First name
  • Last name
  • List of role references
  • Language
  • Locale

The role list should be an array of role Uniform Resource Identifiers (URIs). These URIs in REST calls are in the form /tag/id — for example, /roles/53 for an Administrator role. This example shows how user data can be specified in an XML data element in the REST request:

<user>
  <userid>billtester@test.com</userid>
  <name>Bill Tester</name>
  <first_name>Bill</first_name>
  <last_name>Tester</last_name>
  <roles>
    <role uri="/roles/53" />
   </roles>
  <language>EN</language>
  <locale>en_US</locale>
</user>

An equivalent JSON object is:

{ "user":
  { "userid":"billtester@test.com",
    "name":"Bill Tester",
    "first_name":"Bill",
    "last_name":"Tester",
    "roles":[
        {"uri":"/roles/ro53"}],
    "language":"EN",
    "locale":"en_US"
  }
}

Now you can put together a cURL command to create a new user with the Administrator role. This command uses XML:

curl -k -u johntester@test.com:johnspasswd -X POST -H "Content-Type:application/xml" -d 
"<user><userid>billtester@test.com</userid><name>Bill Tester</name><first_name>Bill
</first_name><last_name>Tester</last_name><roles><role uri=\"/roles/53\"/></roles>
<language>EN</language><locale>en_US</locale></user>" https://endpoint_URL/users

Or, you can use JSON:

curl -k -u johntester@test.com:johnspasswd -X POST -H "ContentType:application/json" 
-d "{\"user\":{\"userid\":\"billtester@test.com \",\"name\":\"Bill Tester\",
\"first_name\":\"Bill\",\"last_name\": \"Tester\",\"roles\":[{\"uri\":\"/roles/53\"}],
\"language\":\"EN\",\"locale\":\"en_US\"}}" https://endpoint_URL/users

Issuing such requests does not cause an immediate response from SmartCloud Enterprise+. Instead, the job of creating a user is initiated, and the requesting user receives email notifications about the job's progress.

Create teams

After you create all participating users, you must create a SmartCloud Enterprise+ team. First, you must determine the Line of Business (LOB) ID, which is provided during the onboarding process:

curl -k -X GET -u johntester@test.com:johnspasswd https://endpoint_URL/lobs

For our examples' purposes, assume that the ID is 8888. Next, create an empty team:

curl -k -u johntester@test.com:johnspasswd -X POST -H "Content-Type:application/xml" -d 
"<team><name>Test Team</name><description>Project XYZ Test Team</description><lob uri=
\"/lobs/8888\"/></team>" https://endpoint_URL/teams

Finally, add an array of users to the empty team. In this example, the team ID is 9999, and the user IDs are 1001, 1002, and 1003:

curl -k -u johntester@test.com:johnspasswd -X POST -H "Content-Type:application/xml" -d 
"<team><name>Test Team 1</name><description>Project XYZ Test Team</description><lob uri=
\"/lobs/8888\"/><users>[{\"uri\":\"/users/1001\"}{\"uri\":\"/users/1002\"}{\"uri\":\
"/users/1003\"}]</users></team>" https://endpoint_URL/teams/9999

Create projects

Now you're ready to create a SmartCloud Enterprise+ project — the administrative unit to which SmartCloud Enterprise+ servers must be associated. You create projects by creating a group, which is a container in which server instances are kept. In this example, the team URL is specified as a value of the option with name of team:

curl -k -u johntester@test.com:johnspasswd -X POST -H "Content-Type:application/xml" -d 
"<group><name>Project XYZ</name><description>Project XYZ Description</description>
<options><option><name>team</name><value><team uri=\"/teams/9999\"/></value></option>
</options></group>" https://endpoint_URL/groups

Create server instances

You're are now ready to instantiate the SmartCloud Enterprise+ servers. You can issue REST GET commands to determine the IDs for:

  • Virtual machine configuration
  • Image
  • Project (group)
  • Security zone
  • Service level agreement
  • Patch schedule category

After the IDs are available, you can specify the XML (or JSON) element that describes the desired instance, then put that element into a cURL command to create the instance:

curl -k -u johntester@test.com:johnspasswd -X POST -H "Content-Type:application/xml" -d 
"<instance><vm_configuration>/vm_configurations/2</vm_configuration><image uri=
\"/images/1033\"/><options><option><name>group</name><value><group uri=\"/groups/638\"/>
</value></option><option><name>security_zone</name><value><security_zone uri=
\"/security_zones/130\"/></value></option><option><name>sla</name><value><sla uri=
\"/slas/135\"/></value></option><option><name>patch_schedule_category</name><value>
<patch_schedule_category uri=\"/patch_schedule_categories/150\"/></value></option>
</options></instance>" https://endpoint_URL/instances

The preceding cURL command initiates the instance-creation job. You can inquire about the job status by issuing this command:

curl -k -X GET -u johntester@test.com:johnspasswd https://endpoint_URL/jobs

The response to the preceding jobs command tells you the status of all recent johntester jobs. If you get the ID of a particular job, you can then retrieve its details by specifying the ID in the command. In this example, assume that the job ID is 1234:

curl -k -X GET -u johntester@test.com:johnspasswd https://endpoint_URL/jobs/1234

Configure server instances

When the instance is up and running, you can change its configuration within allowed limits. For example, you can add an extra disk. In this example, assume that instance has an ID of 3456:

curl -k -u johntester@test.com:johnspasswd -X PUT -H "Content-Type:application/xml" -d 
"<instance><disks><disk><name>disk1</name><size>64</size><options><option>
<name>type</name><value>additional</value></option></options></disk></disks></instance>" 
https://endpoint_URL/instances/3456

Delete an instance

Finally, when an instance is no longer needed (for example, after testing is complete), you can delete it with this command:

curl -k -u johntester@test.com:johnspasswd -X DELETE  https:// endpoint_URL/3456

Conclusion

This article showed you how to perform certain SmartCloud Enterprise+ management tasks programmatically by using the SmartCloud Enterprise+ APIs.

Some characteristics of the SmartCloud Enterprise+ APIs differentiate them from other IBM cloud offerings, such as SmartCloud Enterprise (SCE):

  • The functional scope of SmartCloud Enterprise+ APIs is more limited because of the managed character of SmartCloud Enterprise+, in which the highly controlled cloud environment prevents some user actions. For example, private image catalogs do not exist in the current SmartCloud Enterprise+ release.
  • Creation and update requests can take hours to days rather than minutes, because the monitoring infrastructure must be created or updated accordingly. To accomplish these tasks, SmartCloud Enterprise+ jobs are created. Users issuing the API calls receive email messages at their registered email address informing them of the progress and completion of their jobs.
  • Requests issued by users who have the assigned role of Customer Administrator might need to be approved by the user's Customer Business Manager. Specifically, requests that result in additional resource consumption (for example, creation or modification of virtual servers), must be approved by the user's Customer Business Manager.

Resources

Learn

Discuss

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

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Cloud computing on developerWorks


  • Bluemix Developers Community

    Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.

  • Cloud digest

    Complete cloud software, infrastructure, and platform knowledge.

  • DevOps Services

    Software development in the cloud. Register today to create a project.

  • Try SoftLayer Cloud

    Deploy public cloud instances in as few as 5 minutes. Try the SoftLayer public cloud instance for one month.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Cloud computing
ArticleID=952562
ArticleTitle=Call IBM SmartCloud Enterprise+ services programmatically
publish-date=11122013