This document contains a description of the Xen Management API – an interface for remotely configuring and controlling virtualised guests running on a Xen-enabled host.
The XenAPI is presented here as a set of Remote Procedure Calls, with a wire format based upon XML-RPC. No specific language bindings are prescribed, although examples will be given in the python programming language.
Although we adopt some terminology from object-oriented programming, future client language bindings may or may not be object oriented. The API reference uses the terminology classes and objects. For our purposes a class is simply a hierarchical namespace; an object is an instance of a class with its fields set to specific values. Objects are persistent and exist on the server-side. Clients may obtain opaque references to these server-side objects and then access their fields via get/set RPCs.
For each class we specify a list of fields along with their types and qualifiers. A qualifier is one of:
The following types are used to specify methods and fields in the API Reference:
string: Text strings.
int: 64-bit integers.
float: IEEE double-precision floating-point numbers.
datetime: Date and timestamp.
c ref: Reference to an object of class
t set: Arbitrary-length set of values of type
(k → v) map: Mapping from values of type
kto values of type
e enum: Enumeration type with name
e. Enums are defined in the API Reference together with classes that use them.
Note that there are a number of cases where
refs are doubly
linked – e.g. a VM has a field called
VIFs of type
VIF ref set; this field lists
the network interfaces attached to a particular VM. Similarly, the VIF
class has a field called
VM of type
VM ref which references the VM to which the interface is connected.
These two fields are bound together, in the sense that
creating a new VIF causes the
VIFs field of the corresponding
VM object to be updated automatically.
The API reference explicitly lists the fields that are bound together in this way. It also contains a diagram that shows relationships between classes. In this diagram an edge signifies the existance of a pair of fields that are bound together, using standard crows-foot notation to signify the type of relationship (e.g. one-many, many-many).
f, has an RPC accessor associated with it
get_f (r): Takes a
r, that refers to an object and returns the value of
f, with attribute
RW and whose outermost type is
set has the following
additional RPCs associated with it:
add_f (r, v): Adds a new element
v to the set. Since sets cannot contain duplicate values this operation has no action in the case
v was already in the set.
remove_f (r, v): Removes element
v from the set.
f, with attribute RW and whose outermost type is
map has the following
additional RPCs associated with it:
add_to_f (r, k, v): Adds new pair
(k → v)to the mapping stored in
r. Attempting to add a new pair for duplicate key,
k, fails with an
remove_from_f (r, k): Removes the pair with key
kfrom the mapping stored in
Each field whose outermost type is neither
but whose attribute is RW has an RPC accessor associated with it
that sets its value:
set_f (r, v): Sets field
createthat takes as parameters all fields marked RW and RO/constructor. The result of this RPC is that a new persistent object is created on the server-side with the specified field values.
get_by_uuid (uuid)RPC that returns the object of that class that has the specified UUID.
name_labelfield has a
get_by_name_label (name_label)RPC that returns a set of objects of that class that have the specified
destroy (r)RPC that explicitly deletes the persistent object specified by
rfrom the system. This is a non-cascading delete – if the object being removed is referenced by another object then the
destroycall will fail.
As well as the RPCs enumerated above, most classes have additional RPCs associated with them. For example, the VM class has RPCs for cloning, suspending, starting etc. Such additional RPCs are described explicitly in the API reference.