small bug in proxmox api docs

uriel · Aug 2, 2020

Hi,

Since I check the current existing Proxmox API client in javascript, I realize that all current javascript APi are... ugly. (all of them relay on curl binary).
I'm now digging to build my own api client.

Can you please change some invalid type in the API JSON?
by replacing:

Code:

minimum" : "0",

by:

Code:

"minimum" : 0,

there are 23 similar error.

example:

Code:

bwlimit" : {
    default" : "migrate limit from datacenter or storage config",
    description" : "Override I/O bandwidth limit (in KiB/s).",
    minimum" : "0",
    optional" : 1,
    type" : "number",
    typetext" : "<number> (0 - N)"
},

can you also replace :

Code:

optional" : "1",

by:

Code:

optional" : 1,

there are 4 similar error.

and a question:
what is the difference between integer and number types ?

"type" : "number" is used 154 times
"type" : "integer" is used 845 times.

dietmar · Aug 3, 2020

Please report a bug at https://bugzilla.proxmox.com

fabian · Aug 3, 2020

for optional it's actually correct, as that is a boolean, which in our API is a string that accepts '0|1|on|off|yes|no|true|false'

but passing in integer/number 1/0 also works, since that gets converted to a string anyway in our backend.

the difference between number and integer is simple, integer is for integers (0, 1, -1, 2, -2, 3, -3, 4, ..), the other is for arbitrary numbers including floating point (the exact RE is /^[+-]?(\d+\.\d+|\d+\.|\.\d+|\d+)([eE][+-]?\d+)?$/, that module will probably explain some other stuff related to the Schema as well

)

that being said, encoding booleans, minimum, maximum, length, etc. properly in the API dump makes a lot of sense - so please do file an issue as dietmar suggested, or if you are up for it, even send patches

the schema dump used for the API viewer is generated in the pve-docs repository, the core schema code is in pve-common.

uriel · Aug 3, 2020

Thanks for your lighting, after spending some hours, on the pve API, building an API might be more difficult than expected, but is still possible.

the most complex part is to support requires parameters constraint at build time.

I had expect to build an API like this one:
https://www.npmjs.com/package/@ovh-api/api

Using a syntax like that:

Code:

    const archive = await dbaas.logs.$(serviceName).output.graylog.stream.$(streamId).archive.$(archiveId).$get();
    // call API      GET /dbaas/logs/{serviceName}/output/graylog/stream/{streamId}/archive/{archiveId}

in Proxmox case it will be something like that:

Code:

//  POST /api2/json/nodes/{node}/qemu/{vmid}/clone
await api.nodes.$(node).qemu.$(vmid).clone.$post({newid: 200, node, id: 100});
// in modern JavaScript {newid: 200, node, id: 100} is read as {"newid": 200, "node": node, "id": 100}
// so that the real code.

await api.nodes.$(node).qemu.$(vmid).clone.$post({newid: 200, node});
// will throws an error at compilation time because id is mandatory

await api.nodes.$(node).qemu.$(vmid).clone.$post({newid: 200, node, id: 100, foo: 'bar'});
// will throws an error at compilation time because foo is unexpected.

uriel · Sep 16, 2020

I have start the implementation, and it's already working:

github

Using the API the code looks like that:

JavaScript:

import { proxyProxmox } from "./contructor";
import ProxmoxEngine from "./ProxmoxEngine";

async function test() {
    // authorize self signed cert
    process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
    // load sample authentification info
    const auth = await import('../../../auth');
    const { host, password }  = auth.default;
    // connect to proxmox
    const promox = proxyProxmox(new ProxmoxEngine({host, password}));
    // liste nodes
    const nodes = await promox.nodes.$get();
    // iterate cluster nodes
    for (const node of nodes) {
        const theNode = promox.nodes.$(node.node);
        // list Qemu VMS
        const qemus = await theNode.qemu.$get({full:true});
        // iterate Qemu VMS
        for (const qemu of qemus) {
            // do some suff.
            const config = await theNode.qemu.$(qemu.vmid).config.$get();
            console.log(`vm: ${config.name}, memory: ${config.memory}`);
            // const vnc = await theNode.qemu.$(qemu.vmid).vncproxy.$post();
            // console.log('vnc:', vnc);
            const spice = await theNode.qemu.$(qemu.vmid).spiceproxy.$post();
            console.log('spice:', spice);
        }
    }    
}
test().catch(console.error);

And the IDE intelligent works on every part of the code, no need to check any external docs.

I need some more test before any public release.

uriel · Sep 16, 2020

the model from:
https://pve.proxmox.com/pve-docs/api-viewer/
is not up to date.

for example in https://pve.proxmox.com/pve-docs/api-viewer/#/nodes/{node}/qemu/{vmid}/status/current
template filed is missing from responce.

as my api client is based on this swagger, fields are missing too.

Can anyone regenerated it from up to date plateforme ?

fabian · Sep 16, 2020

the one representing your system's copy is shipped as part of pve-docs, but both return and parameter schemas might have 'additionalproperties' set to true, in which case they allow extra keys/values..

uriel · Sep 16, 2020

hi,

I had just implement 'additionalProperties' as accept any other parameters, but I do not help, and I had to change the original model to mate it works, by adding an additionalProperties: 1.

JSON:

{
   "info" : {
      "GET" : {
         "allowtoken" : 1,
         "description" : "Get virtual machine status.",
         "method" : "GET",
         "name" : "vm_status",
         "parameters" : {
            "additionalProperties" : 0, // if set to one can accepte extra param ?
            "properties" : {
               "node" : {
                  "description" : "The cluster node name.",
                  "format" : "pve-node",
                  "type" : "string",
                  "typetext" : "<string>"
               },
               "vmid" : {
                  "description" : "The (unique) ID of the VM.",
                  "format" : "pve-vmid",
                  "minimum" : 1,
                  "type" : "integer",
                  "typetext" : "<integer> (1 - N)"
               }
            }
         },
         "permissions" : {
            "check" : [
               "perm",
               "/vms/{vmid}",
               [
                  "VM.Audit"
               ]
            ]
         },
         "protected" : 1,
         "proxyto" : "node",
         "returns" : {
           "additionalProperties" : 1, // is not present in the originakl json
            "properties" : {
               "agent" : {
                  "description" : "Qemu GuestAgent enabled in config.",
                  "optional" : 1,
                  "type" : "boolean"
               },
            // droped json
               "vmid" : {
                  "description" : "The (unique) ID of the VM.",
                  "format" : "pve-vmid",
                  "minimum" : 1,
                  "type" : "integer"
               }
            },
            "type" : "object"
         }
      }
   },
   "leaf" : 1,
   "path" : "/nodes/{node}/qemu/{vmid}/status/current",
   "text" : "current"
}

there is only 7 "additionalProperties" : 1 in the swagger.
the method I trying to call do not have one of them.

fabian · Sep 17, 2020

yes, the default is 1 so it's often omitted. we could maybe add it to the apidump in all cases where it is not set explicitly..

uriel · Sep 17, 2020

Implemented as 1 by default.

Release time...

published as:
https://www.npmjs.com/package/proxmox-api

r.jochum · Sep 17, 2020

Very nice, thanks!

uriel · Sep 18, 2020

Now that my new Api is working, I would like to submit some improvement to the main swagger.

which git should I clone for changes proposal ?
you have a lot of them: https://git.proxmox.com/

I can make some change in my own copy, but that not the best way to process.

------
I started to clone all the repository to find the right git, it will just take some times.

fabian · Sep 18, 2020

that would be great!

check out

https://pve.proxmox.com/wiki/Developer_Documentation (general guidelines and workflow)
https://git.proxmox.com/?p=pve-common.git;a=blob;f=src/PVE/JSONSchema.pm; (contains most of the basic machinery for our API schema)
https://git.proxmox.com/?p=pve-common.git;a=blob;f=src/PVE/RESTHandler.pm; (contains the code that actually generates the API dump)
https://git.proxmox.com/?p=pve-docs.git;a=blob;f=extractapi.pl; (the repo + code where the dump gets converted to the JS file that the API viewer uses)

uriel · Sep 18, 2020

by the way,
the first time I called : `GET /nodes/{node}/qemu`
with the code: `qemus = await theNode.qemu.$get({full:true});`

I get an error saying that 'true' wasn't a correct boolean, and I had to convert all my boolean to 0 or 1.

bot a big deal, but strange.
a 'fabian' proxmox user told me that:

for optional it's actually correct, as that is a boolean, which in our API is a string that accepts '0|1|on|off|yes|no|true|false'

but passing in integer/number 1/0 also works, since that gets converted to a string anyway in our backend.

fabian · Sep 21, 2020

you are correct - the type checking in the API is stricter than the parser later on. in config files, all those values are accepted, but in the API, only 1/0 get through the type checker.

uriel · Sep 23, 2020

I Used most of the data swagger,

for now:
- permissions is not used, it's that not very important for an API, this more a sys-op info.
- I do not know what the field protected is for.
- I do not know what the field leaf is for.

for now pattern regex can not be enforce by typescript;
the min/max length can only be enforced using extra heavy typescript syntax, I prefer not to use it.
I have no way to distinguish integer from number.

the requires field can be enforced, but may create a lots of new conditional typing, So not for now.
some complex format fields can be converted to be more human readable.

That its.

the current version is now 0.0.4 a 0.0.5 is on the way.

fabian · Sep 24, 2020

uriel said:
- I do not know what the field protected is for.
- I do not know what the field leaf is for.

protected means that this API endpoint is proxied to pvedaemon running as root (e.g., because it needs to do storage operations that pveproxy/www-data can't do).

leaf simply means that when looking at the API as tree, that endpoint has no children.

Search

Search

small bug in proxmox api docs

uriel

Member

dietmar

Proxmox Staff Member

fabian

Proxmox Staff Member

uriel

Member

uriel

Member

uriel

Member

fabian

Proxmox Staff Member

uriel

Member

fabian

Proxmox Staff Member

uriel

Member

r.jochum

Renowned Member

uriel

Member

fabian

Proxmox Staff Member

uriel

Member

fabian

Proxmox Staff Member

uriel

Member

fabian

Proxmox Staff Member