[Xen-API] Comments on Xen API document

[John Levon <john.levon@xxxxxxx>]

I've only recently joined this mailing list, so I'm sure some of my questions
here are old hat - in which case apologies. Same goes for ones that are a
result of my limited knowledge about XML RPC.

These comments are based on version 0.4 from the wiki page.

Generally - there's no clear versioning. In particular a description of how to
find out what version of this API the host expects, and what it will return.
Ideally it would degrade to the version that the client reports as being able
to handle. The API docs should in the future clearly label what revision things
were added in. One thing that might be useful is clearly specifying stability
of each item. This nicely allows for experimental features, whilst labelling
truly stable entries clearly.

I think you mention it, but all calls need to clearly define the failure modes
and what gets returned on failure. It also wasn't clear to me what happens if I
try to set several parameters in a single XML RPC call (presuming that's
possible?). If the second one fails, what do I get back in terms of the error
struct?

1.1

The add_to_* primitives for sets should probably return the equivalent of
EEXIST, not just silently succeed: it's always better to provide more
information to a client. The operation may be a logic error.

1.3.1

ErrorDescription isn't specified well enough to program against.

1.4.2

What happens to the session if a connection is terminated or idles out?

1.4.3

The persistent tasks per user behaviour should be called out here explicitly,
rather than the comment later on in the document.

The specification implies that a failed task must have its Progress set to
"100". This seems odd. More widely, has there been consideration of indicating
/phases/ of operation? Often this is more useful than a generic slider value.

1.5

I don't understand the expanded XML for the do_login_with_password() - the
paramters are not name/value pairs. If this is a general design, how are
optional parameters to be handled?

"getname_label" is a result, presumably, of the odd "name/label" naming of the
parameter. This mapping is not defined in the document, and it's a little odd
that we have "getname_label" but "get_uuid".


Probably an XML RPC thing, but there's no discussions of transactions in the
document. Can I change a batch of things and assure it's done atomically?

1.7

Do zombie domains need to be explicitly called out in the lifecycle?

2.3.3

These enums would be easier to read if placed by the calls that used them.

enum vm_power_state - "power" is a very odd notion for a VM. Why not just
"vm_state" ?

enum on_crash_behaviour - it's likely useful to have a host-wide setting for
whether domains should core dump. How would that interact?

enum boot_type - it's not clear to me how a client would make use of knowing
that it's "kernel_internal"

2.6.1

is_a_template - "is_template" seems more natural

memory/* needs units

VCPUs/params needs a detailed description of what it can/does contain

VCPUS/utilisation - a percentage presumably?

bios/cdrom - I'm not sure what this does...

kernel/kernel et al - depending on bootloader, is this the copied kernel path
on dom0 filesystem, or the path inside the domU filesystem? e.g. pygrub,
domuloader

tools_version - needs defining explicitly?

There's no mapping from VM vcpus to the host_cpu's it's pinned on.

2.6.2

What's the interaction with the on shutdown behaviour for the shutdown RPCs?

suspend/resume - I'm a little confused about where the domain save file
actually goes, and how 'xm' will specify it

2.7.1

What is name/label intended to be for a host? It's not actually entirely clear
to me what a host /is/. What does "list" do? Note that early in the document
you refer to a non-existent ListAllVMs RPC.

'disable' and 'enable' seem perhaps a bit too generic name-wise.

2.11

I'm not clear on what an SR actually is and its relationship to its contained
VDIs. Could the document clarify this somewhat?

type,location - what are its possible values?

2.12.1

"shareable" just wins in a googlefight against "sharable"

2.12.2

Why is a snapshot defined as living in the same SR?

2.13.1

I don't think vbd_mode or driver_type are specified.

thanks,
john

_______________________________________________
xen-api mailing list
xen-api@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/cgi-bin/mailman/listinfo/xen-api