XenServer Software Development Kit Guide 4.1.0

Chapter 3. Overview of the XenServer

API

In this chapter we introduce the XenServer API (hereafter referred to as just "the API") and its associated

object model. The API has the following key features:

• Management of all aspects of XenServer Host: Through the API one can manage VMs, storage,

networking, host configuration and pools. Performance and status metrics can also be queried via the API.

• Persistent Object Model: The results of all side-effecting operations (e.g. object creation, deletion

and parameter modifications) are persisted in a server-side database that is managed by the XenServer

installation.

• An event mechanism: Through the API, clients can register to be notified when persistent (serv-

er-side) objects are modified. This enables applications to keep track of datamodel modifications per-

formed by concurrently executing clients.

• Synchronous and asynchronous invocation: All API calls can be invoked synchronously (i.e. block

until completion); any API call that may be long-running can also be invoked asynchronously. Asyn-

chronous calls return immediately with a reference to a task object. This task object can be queried

(through the API) for progress and status information. When an asynchronously invoked operation com-

pletes, the result (or error code) is available via the task object.

• Remotable and Cross-Platform: The client issuing the API calls does not have to be resident on the

host being managed; nor does it have to be connected to the host via ssh in order to execute the API.

API calls make use of the XML-RPC protocol to transmit requests and responses over the network.

• Secure and Authenticated Access: The XML-RPC API server executing on the host accepts secure

socket connections. This allows a client to execute the APIs over the https protocol. Further, all the API

calls execute in the context of a login session generated through username and password validation at

the server. This provides secure and authenticated access to the XenServer installation.

3.1. Getting Started with the API

We will start our tour of the API by describing the calls required to create a new VM on a XenServer instal-

lation, and take it through a start/suspend/resume/stop cycle. This is done without reference to code in any

specific language; at this stage we just describe the informal sequence of RPC invocations that accomplish

our "install and start" task.

3.1.1. Authentication: acquiring a session reference

The first step is to call Session.login(username, password). The API is session based, so before you

can make other calls you need to authenticate with the server. Assuming the username and password are

authenticated correctly, the result of this call is a session reference. Subsequent API calls take the session

reference as a parameter. In this way we ensure that only API users who are suitably authorized can perform

operations on a XenServer installation.

3.1.2. Acquiring a list of templates to base a new VM installation on

The next step is to query the list of "templates" on the host. Templates are specially-marked VM objects

that specify suitable default parameters for a variety of supported guest types. (If you want to see a quick