7:50 p.m.
On 05/02/2014 02:44 PM, Sven Kieske wrote:
Hi,
there's an inconsistent use of plural
vs singular form regarding the "vm" collection
in the apis.
in json you got a collection named
"vm" which contains a list of vms.
in xml and via gui you got a collection
"vms" which contains a list of vms.
I just stumbled upon it, as I used
json api already in 3.3.3.
and didn't had time to test 3.4 until
now.
I believe that this inconsistency doesn't exist in 3.4. The result of
listing VMs is the following with JSON:
{
"vm" : [
{
"name": "myvm",
...
},
{
"name": "yourvm",
...
},
...
]
}
The name of the array is "vm", in singular.
With XML the result is the following:
<vms>
<vm>
<name>myvm</name>
...
</vm>
<vm>
<name>yourvm</name>
...
</vm>
...
</vms>
There are two notable differences in these representations:
1. XML requires a "root" tag, in this case "vms", in plural. This
isn't
needed in JSON, and thus it isn't used. In general, all the root tags
for collections will be in plural when using XML and won't be present in
JSON.
2. In XML arrays are represented as a set of tags named in singular,
"vm" in this case, because XML doesn't have the array concept. In JSON
there is only one "vm" element because JSON does have the concept of
array, so the name of the array has to be given only once. The name of
these XML tags and the name of the JSON array will anyhow be the same,
in singular. There may be exceptions where the name is in plural, but
you can consider them bugs, and they will affect both XML and JSON, so
in those cases we will be consistently buggy.
the upgrade itself went very well, but
know I have to deal with this api change
and the other entity renamings done
in json api.
what would make this less painful
would be an consistent way of getting
the ovirt-version via api, so I could
easily split my codepath by first
querying the api version.
unfortunately also this one got changed
in json so I'll need to call for every
version that might be there.
The way to find the version will be stable now that JSON is supported,
you can count on that. So in the future you should be able to get the
version number in a consistent way. What I mean is that we guarantee
that the version info will always appears as follows:
GET /ovirt-engine/api
{
...
"product_info" : {
"vendor" : "ovirt.org",
"version" : {
"major" : "3",
"minor" : "4",
"build" : "0",
"revision" : "0"
},
"full_version" : "3.4.1-0.0.master.20140430080728.fc20",
"name" : "oVirt Engine"
},
...
}
If you ever see something changing in a backwards incompatible way
there, it will be a bug.
I understand that part of this problem
comes from using json when it was not
"official supported", but at least
this inconsistence use in different
apis makes not really much sense to me.
should I file a BZ for this?
--
Dirección Comercial: C/Jose Bardasano Baos, 9, Edif. Gorbea 3, planta
3ºD, 28016 Madrid, Spain
Inscrita en el Reg. Mercantil de Madrid – C.I.F. B82657941 - Red Hat S.L.