@@ -3,14 +3,16 @@ title = "XenAPI Basics"
33weight = 10
44+++
55
6- This document contains a description of the Xen Management API – an interface for
6+ This document contains a description of the Xen Management API - an interface for
77remotely configuring and controlling virtualised guests running on a
88Xen-enabled host.
99
10- The XenAPI is presented here as a set of Remote Procedure Calls, with a wire
11- format based upon [ XML-RPC] ( http://xmlrpc.scripting.com ) .
12- No specific language bindings are prescribed,
13- although examples will be given in the python programming language.
10+ The API is presented here as a set of Remote Procedure Calls (RPCs).
11+ There are two supported wire formats, one based upon
12+ [ XML-RPC] ( http://xmlrpc.scripting.com/spec.html )
13+ and one based upon [ JSON-RPC] ( http://www.jsonrpc.org ) (v1.0 and v2.0 are both
14+ recognized). No specific language bindings are prescribed, although examples
15+ are given in the Python programming language.
1416
1517Although we adopt some terminology from object-oriented programming,
1618future client language bindings may or may not be object oriented.
@@ -21,98 +23,102 @@ specific values. Objects are persistent and exist on the server-side.
2123Clients may obtain opaque references to these server-side objects and then
2224access their fields via get/set RPCs.
2325
24- For each class we specify a list of fields along with their _ types_ and _ qualifiers _ . A
25- qualifier is one of:
26+ For each class we specify a list of fields along with their _ types_ and
27+ _ qualifiers _ . A qualifier is one of:
2628
27- - _ RO/runtime_ : the field is Read
28- Only. Furthermore, its value is automatically computed at runtime.
29- For example: current CPU load and disk IO throughput.
30- - _ RO/constructor_ : the field must be manually set
31- when a new object is created, but is then Read Only for
32- the duration of the object's life.
33- For example, the maximum memory addressable by a guest is set
34- before the guest boots.
35- - _ RW_ : the field is Read/Write. For example, the name of a VM.
29+ - _ RO/runtime_ : the field is Read Only. Furthermore, its value is
30+ automatically computed at runtime. For example, current CPU load and disk IO
31+ throughput.
3632
37- Types
38- -----
33+ - _ RO/constructor_ : the field must be manually set when a new object is
34+ created, but is then Read Only for the duration of the object's life.
35+ For example, the maximum memory addressable by a guest is set
36+ before the guest boots.
37+
38+ - _ RW_ : the field is Read/Write. For example, the name of a VM.
39+
40+ ## Types
3941
4042The following types are used to specify methods and fields in the API Reference:
4143
42- - ` string ` : Text strings.
43- - ` int ` : 64-bit integers.
44- - ` float ` : IEEE double-precision floating-point numbers.
45- - ` bool ` : Boolean.
46- - ` datetime ` : Date and timestamp.
47- - ` c ref ` : Reference to an object of class ` c ` .
48- - ` t set ` : Arbitrary-length set of values of type ` t ` .
49- - ` (k → v) map ` : Mapping from values of type ` k ` to values of type ` v ` .
50- - ` e enum ` : Enumeration type with name ` e ` . Enums are defined in the API Reference together with classes that use them.
51-
52- Note that there are a number of cases where ` ref ` s are _ doubly
53- linked_ – e.g. a VM has a field called ` VIFs ` of type
54- ` VIF ref set ` ; this field lists
55- the network interfaces attached to a particular VM. Similarly, the VIF
56- class has a field called ` VM ` of type ` VM ref ` which references the VM to which the interface is connected.
44+ - ` string ` : Text strings.
45+ - ` int ` : 64-bit integers.
46+ - ` float ` : IEEE double-precision floating-point numbers.
47+ - ` bool ` : Boolean.
48+ - ` datetime ` : Date and timestamp.
49+ - ` c ref ` : Reference to an object of class ` c ` .
50+ - ` t set ` : Arbitrary-length set of values of type ` t ` .
51+ - ` (k -> v) map ` : Mapping from values of type ` k ` to values of type ` v ` .
52+ - ` e enum ` : Enumeration type with name ` e ` . Enums are defined in the API
53+ reference together with classes that use them.
54+
55+ Note that there are a number of cases where ` ref ` s are _ doubly linked_ .
56+ For example, a ` VM ` has a field called ` VIFs ` of type ` VIF ref set ` ;
57+ this field lists the network interfaces attached to a particular VM.
58+ Similarly, the ` VIF ` class has a field called ` VM ` of type ` VM ref `
59+ which references the VM to which the interface is connected.
5760These two fields are _ bound together_ , in the sense that
5861creating a new VIF causes the ` VIFs ` field of the corresponding
5962VM object to be updated automatically.
6063
61- The API reference explicitly lists the fields that are
64+ The API reference lists explicitly the fields that are
6265bound together in this way. It also contains a diagram that shows
6366relationships between classes. In this diagram an edge signifies the
64- existance of a pair of fields that are bound together, using standard
67+ existence of a pair of fields that are bound together, using standard
6568crows-foot notation to signify the type of relationship (e.g.
6669one-many, many-many).
6770
68- RPCs associated with fields
69- ---------------------------
71+ ## RPCs associated with fields
72+
73+ Each field, ` f ` , has an RPC accessor associated with it that returns ` f ` 's value:
74+
75+ - ` get_f (r) ` : takes a ` ref ` , ` r ` that refers to an object and returns the value
76+ of ` f ` .
77+
78+ Each field, ` f ` , with qualifier _ RW_ and whose outermost type is ` set ` has the
79+ following additional RPCs associated with it:
7080
71- Each field, ` f ` , has an RPC accessor associated with it
72- that returns ` f ` 's value:
81+ - ` add_f(r, v) ` : adds a new element ` v ` to the set.
82+ Note that sets cannot contain duplicate values, hence this operation has
83+ no action in the case that ` v ` is already in the set.
7384
74- - ` get_f (r )` : Takes a ` ref ` , ` r ` , that refers to an object and returns the value of ` f ` .
85+ - ` remove_f(r, v )` : removes element ` v ` from the set .
7586
76- Each field, ` f ` , with attribute ` RW ` and whose outermost type is ` set ` has the following
77- additional RPCs associated with it:
87+ Each field, ` f ` , with qualifier _ RW _ and whose outermost type is ` map ` has the
88+ following additional RPCs associated with it:
7889
79- - ` 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
80- that ` v ` was already in the set.
90+ - ` add_to_f(r, k, v) ` : adds new pair ` k -> v ` to the mapping stored in ` f ` in
91+ object ` r ` . Attempting to add a new pair for duplicate key, ` k ` , fails with a
92+ ` MAP_DUPLICATE_KEY ` error.
8193
82- - ` remove_f (r, v) ` : Removes element ` v ` from the set.
94+ - ` remove_from_f(r, k) ` : removes the pair with key ` k `
95+ from the mapping stored in ` f ` in object ` r ` .
8396
84- Each field, ` f ` , with attribute RW and whose outermost type is ` map ` has the following
85- additional RPCs associated with it:
97+ Each field whose outermost type is neither ` set ` nor ` map ` , but whose
98+ qualifier is _ RW _ has an RPC accessor associated with it that sets its value :
8699
87- - ` add_to_f (r, k, v) ` : Adds new pair ` (k → v) ` to the mapping stored in ` f ` in object ` r ` . Attempting to add a new pair for duplicate
88- key, ` k ` , fails with an ` MAP_DUPLICATE_KEY ` error.
89- - ` remove_from_f (r, k) ` : Removes the pair with key ` k ` from the mapping stored in ` f ` in object ` r ` .
100+ - ` set_f(r, v) ` : sets the field ` f ` on object ` r ` to value ` v ` .
90101
91- Each field whose outermost type is neither ` set ` nor ` map ` ,
92- but whose attribute is RW has an RPC accessor associated with it
93- that sets its value:
102+ ## RPCs associated with classes
94103
95- - ` set_f (r, v) ` : Sets field ` f ` on object ` r ` to value ` v ` .
104+ - Most classes have a _ constructor_ RPC named ` create ` that
105+ takes as parameters all fields marked _ RW_ and _ RO/constructor_ . The result
106+ of this RPC is that a new _ persistent_ object is created on the server-side
107+ with the specified field values.
96108
97- RPCs associated with classes
98- ----------------------------
109+ - Each class has a ` get_by_uuid(uuid) ` RPC that returns the object
110+ of that class that has the specified ` uuid ` .
99111
100- - Most classes have a _ constructor_ RPC named ` create ` that
101- takes as parameters all fields marked RW and
102- RO/constructor. The result of this RPC is that a new _ persistent_ object is
103- created on the server-side with the specified field values.
104- - Each class has a ` get_by_uuid (uuid) ` RPC that returns the object
105- of that class that has the specified UUID.
106- - Each class that has a ` name_label ` field has a ` get_by_name_label (name_label) ` RPC that returns a set of objects of that
107- class that have the specified ` name_label ` .
108- - Most classes have a ` destroy (r) ` RPC that explicitly deletes the persistent object specified by ` r ` from the system. This is a
109- non-cascading delete – if the object being removed is referenced by another
110- object then the ` destroy ` call will fail.
112+ - Each class that has a ` name_label ` field has a
113+ ` get_by_name_label(name_label) ` RPC that returns a set of objects of that
114+ class that have the specified ` name_label ` .
111115
112- Additional RPCs
113- ---------------
116+ - Most classes have a ` destroy(r) ` RPC that explicitly deletes
117+ the persistent object specified by ` r ` from the system. This is a
118+ non-cascading delete - if the object being removed is referenced by another
119+ object then the ` destroy ` call will fail.
114120
115- As well as the RPCs enumerated above, most classes have additional RPCs
116- associated with them. For example, the VM class has RPCs for cloning,
121+ Apart from the RPCs enumerated above, most classes have additional RPCs
122+ associated with them. For example, the ` VM ` class has RPCs for cloning,
117123suspending, starting etc. Such additional RPCs are described explicitly
118124in the API reference.
0 commit comments