.NET SDK Design Document

Introduction

This document contains the design specification for the .NET SDK for CloudStack

Purpose

The .NET SDK for CloudStack provides a client side library to allow Microsoft .NET programs to access the CloudStack REST APIs.

Background

The CloudStack API is loosely based on the REST architecture [2]. Whilst providing a good deal of flexibility for a developer, it also has the potential to impose a heavy cost in that the developer is responsible for marshalling all the request arguments into the required format; correctly signing the request; dealing with asynchronous methods; handling fault conditions and parsing the response fields.

The .NET SDK for CloudStack addresses these issues for developers in the Microsoft .NET environment by concealing all of these implementation details underneath a high level request/response API that is directly accessible from all .NET supported languages.

References

1. CloudStack API Reference: http://docs.cloudstack.org/CloudStack_Documentation/API_Reference%3A_CloudStack
2. CloudStack API Developers Guide: http://docs.cloudstack.org/CloudStack_Documentation/Developer's_Guide%3A_CloudStack

Feature Specification

The .NET SDK for CloudStack provides a programmatic set of methods callable from .NET code.

Session Management and Authentication

Session management is provided to enable the developer to simplify a multi request/response conversation with a CloudStack server. A client session is constructed from a URL (or the CloudStack API server) plus a set of client credentials (apiKey and secretKey). For example:

public class Client : IDisposable
{
  public Client (Uri serverUri, string apiKey, SecureString secretKey) { … }
   …
}

The server Uri, apiKey and secretKey are securely cached within the client session object and used to sign each request that is sent to the CloudStack server.  The session class will securely delete the secret key during object disposal.

Strongly Typed API

The pattern adopted for the .NET SDK for CloudStack is to expose one method per CloudStack API command. The method will have a fixed operation contract with strongly typed Request and Response data contracts. For example the CloudStack API command attachVolume is exposed in the .NET SDK for CloudStack as method with signature:

interface ICloudStackSDK
{
    …
    AttachVolumeResponse attachVolume (AttachVolumeRequest request);
    …
};

The Request and Response classes have the expected properties, for example:

public class AttachVolumeRequest : APIRequest
{
    public string Id { … }
    public string VirtualMachineId { … }
    public string DeviceId { … }
}

So a typical usage of the strongly typed API of the .NET SDK for CloudStack might look like:

Client client = new Client(serverUri, myApiKey, mySecretKey);
AttachVolumeRequest request = new AttachVolumeRequest ()
{
    Id = myVolumeId,
    VirtualMachineId = myVmId,
    DeviceId = “/dev/xvdc”
};
AttachVolumeResponse response = client.attachVolume(request);

…

This pattern is to be followed for all CloudStack API commands (User API and Admin APIs).  The advantage of this pattern for the .NET SDK for CloudStack is that it enables backwards compatibility; a new version of the NET SDK for CloudStack that introduces new command or response parameters will not break old client code that is not aware of the new parameters as the new parameters do not affect any method signatures, they simply appear as new properties on the request/response classes.

Low Level API

The Strongly Typed API described above is built upon a more generic low level API that is also exposed to the developer.  This takes the form of generic API request and response bases classes and a generic mechanism to send a request to the server and receive a response. The APIRequest class takes a command name as argument to the constructor and exposes a generic string Dictionary to contain any parameters.

public class APIRequest
{
    public APIRequest(string commandName) { ..}\\
    public IDictionary<string, string> Parameters { get; private set; }
    …
}

A typical usage of the low level API may look like:

Client client = new Client(serverUri, myApiKey, mySecretKey);
APIRequest request = new APIRequest (“listaccounts”);
request.Parameters\[“accounttype”\] = “admin”;
APIResponse response = client.SendRequest(request);
Console.Writeline (“Raw XML response: {0}”, response.XmlResponse);

This gives the .NET SDK for CloudStack a forward compatibility with any new version of the CloudStack server – for example if and old version of the Strongly Typed API does not support a new request parameter it can be “manually” added to the request object via the low level API.

Impersonation

Many of the CloudStack API “create” commands allow for an administrator to create resources on behalf of another user by specifying a pair of optional parameters named account and domainId; if the caller has the appropriate rights then the resource will be created in the specified account.

The .NET SDK for CloudStack fully supports this pattern both in the strongly typed and low level APIs, but also provides a more flexible model that takes impersonation out of line, and allows a user to create an impersonating session that can be used to create resources on behalf of another user:

Client client = new Client(serverUri, myApiKey, mySecretKey);

Client fred = client.Impersonate (“fred-account”, “fred-domain-id”);

After this, the session named “fred” may be used anywhere that a regular session would be used, but create operations will be carried out on behalf of the specified user.

Use Cases

The .NET SDK for CloudStack is intended to support client side access to the CloudStack API from .NET languages.

Architecture and Design Description

The API architecture and design is covered in the Feature Specification; in this section we will concentrate on implementation; build; test and documentation issues.

Build

The .NET SDK for CloudStack is built as a Visual Studio 2010 solution targeting .NET Framework 4.

Test

The .NET SDK for CloudStack has a rudimentary test program, implemented as a Windows Forms application that lets the developer exercise the main strongly typed API. A good deal more work is required in this area.

Completeness

The .NET SDK for CloudStack is completely implemented, with the exception of the Strongly Typed API which has been partially implemented only with classes that were required by our current project (but see Automatic Code Generation).

Automatic Code Generation

The split of the architecture of the API into high/low level is designed to facilitate automatic code generation of the high level (strongly typed) API; generating code that makes use of the well-defined low level API to implement the strongly typed API.

This work has not yet been started, but given the existence of the automatically generated Python bindings, should not be too onerous to implement.

Documentation

The .NET SDK for CloudStack has a design document (this), but as yet no user guide.