[ovirt-devel] [ovirt-users] inconsistency in json api vs xml/other apis

[Juan Hernandez]

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.