OverviewThe HPCloud API has been designed to give developers an easy, accessible and familiar way to access services delivered by HPs growing cloud offerings. These services are based on the OpenStack Open Source Project and encompass functionality such as Identity Management, Storage and Compute. The .Net 4.0 based client API intends to shield developers from the underlying details of these message exchanges. For more information about HP Cloud Services, see
http://build.hpcloud.comInstallationThis library is available as a NuGet Package or in source form via CodePlex under the MIT License.
NuGet Installation Initially the API will be installed through an isolated NuGet Package located in the downloads section. For details on installing components outside of the official online NuGet source, check out this article.
http://docs.nuget.org/docs/creating-packages/hosting-your-own-nuget-feeds. Also, please read the section below on where to place the APIs config file.
Full Source Installation and RequirementsThe complete source for this project can be found in the Source Code section. A basic test project is also included and is recommended that you check this out for some good examples as to how the API works. The following external libraries are required when working with the source code directly.
*BouncyCastle.Crypto (http://www.bouncycastle.org/csharp/)
*Newtonsoft.Json (http://james.newtonking.com/pages/json-net.aspx)
API Configuration File RequirementThis API uses a configuration file to store information about the users access keys, settings and various other elements. This is the same config file used by our Powershell CLI and as such needs to be placed in the same location. This directory will be the HP folder within the Environment.SpecialFolder.MyDocuments location (i.e C:\Users\someuser\Documents\HP\CLI.config). Below is an example config file for you to use. Make sure that you supply the AccessKey, SecretKey and DefaultTenantId values. These account values can be obtained from the Web based Managment Console at
http://www.HPcloud.com.
CLI.configThe Package ViewBefore we start let's get familiar with the basic assemblies involved and their relationships to one another. If you're installing this from the NuGet package the HPCloud.Objects and HPCloud.Common assemblies will be added to your project automatically by the NuGet Package Manager. A full source install is required for the HPCloud.Objects.Test project.
Getting Started: Creating a new SessionTo start working with any of the available HPCloud services we first need to establish a Session. Session instances contain a list of Services available to a specific user, service entry points (repositories), configuration information and various other items typically required when developing applications against HPCS. It’s simple to establish a session with the following code
Session newSession = Session.CreateSession();The CreateSession static method performs a number of required operations on your behalf such as
• Retrieving locally stored user credentials
• Authenticating against the HP-Identity Service
• Retrieving a Service Catalog and AccessToken for the authenticated User
• Configuring the RepositoryFactory which streams in the required security tokens for each call to HPCS.
The end result of this operation is a Session instance with several key associations that we’ll cover next.
Session.jpgNote For a more in depth discussion of this process please refer to
https://build.hpcloud.com/identity.
Context – The Sessions Context object provides strongly typed access to configuration file entries located in the CLI.config file. In addition, a Token instance is attached to Context exposing the SecurityToken retrieved during the authentication process. Finally a list of Services tailored to the authenticated User is available from the attached ServiceCatalog instance.
ServiceCatalog.jpgEach ServiceCatalog may contain one to many Services. Detailed endpoint information is available for each Service through the Endpoint association. Each service added to the Account through our Management Console application will be reflected here after logging in.
RepositoryFactory – The Sessions RepositoryFactory is your one stop shop for accessing HPCS resources. With this Factory you can request one of several Repositories, each related to a specific HPCS concept. For example if I wanted to work with the Compute service to list out the servers I previously creating within the HPCS Management Console application, I could request a Server repository like so

Throughout the API sets are returned as List<T>. Here we can see the IServerRepository contract in action. In addition to basic CRUD operations against Server, IServerRepository also provides a means of rebooting active servers and working with meta-data assigned to a server. A number of Repositories are available to work with.
Repositories.jpg Note that Repositories consult with the ServiceCatalog to determine if access to that particular HPCS service is available to the User. A SecurityException will be thrown for each call made against backend functionality that the User has not paid for. This prevents a trip to the Server only to receive the same security exception. When making calls against a Repository you can trap for these exceptions yourself or consult with the ServiceCatalog ahead of time.
Working with Domain Objects (HPCloud.Objects.Domain)The above code example required no additional input parameters from the developer. This is not always the case. For instance when creating a new server, we have to pass in an instance of the NewServer class like so

These Domain Objects represent the basic OpenStack concepts provided by HPCS. They reside within the
HP.Objects.Domain namespace, organized by service type.
General Design RecommendationsTo sum this all up let’s take a look at our basic usage pattern of this API
• Build a session
• Request a Repository from the Session
• Make calls against the repository.
Finally I recommend that you create your Session and find ways of keeping it in scope rather than creating it each time you make a call. I also like to place convenience methods around key locations within the Session (i.e the Repository property) to cut down on the amount of code that you have write. We hope that you've found this material helpful. Be sure and visit our Developer Site at http://hpcloud.com/ for an extensive set of examples, tutorials and community discussion around HPs rapidly evolving Cloud Services Infrastructure.
Appendix A: Class Diagram (Excluding Domain Objects)
ClassDiagram.jpgAppendix B : Package View + Namespaces
Namespaces.jpg