About API documentation and stability

[q8zx]

Hello Community,

While playing with the API i noticed some differences between what the an api-call should return and what it actually returns:

pvesh get /nodes/node01/tasks/'UPID:node01:0039A78B:033DA2E3:5F96DF32:qmsnapshot:123:user@pve!token:'/status
┌────────┬─────────┐
│ key    │ value   │
╞════════╪═════════╡
│ pid    │ 3881431 │
├────────┼─────────┤
│ status │ stopped │
└────────┴─────────┘

This reflects the documentation, however, querying the api via curl results in a more detailed response:

{
  "data": {
    "id": "123",
    "status": "stopped",
    "node": "node01",
    "tokenid": "token",
    "starttime": 1603726401,
    "type": "qmsnapshot",
    "pid": 3881431,
    "pstart": 54705336,
    "user": "user@pve",
    "upid": "UPID:node01:003B39D7:0342BCB8:5F96EC41:qmsnapshot:123:user@pve!token:",
    "exitstatus": "OK"
  }
}

The actual response is in fact quite useful, especially the exitstatus-field. I would like to know if these `undocumented` return-values are safe to use or subject to change?

Thanks.

 

[oguz]

hi,

you can get the same response with pvesh if you add --output-format json-pretty in your command:

root@node01:~# pvesh get /nodes/node01/tasks/UPID:node01:0000602B:0005A79A:5EEB7BAA:vzdump:127:root@pam:/status --output-format json-pretty
{
   "exitstatus" : "OK",
   "id" : "127",
   "node" : "node01",
   "pid" : 24619,
   "pstart" : 370586,
   "starttime" : 1592490922,
   "status" : "stopped",
   "type" : "vzdump",
   "upid" : "UPID:node01:0000602B:0005A79A:5EEB7BAA:vzdump:127:root@pam:",
   "user" : "root@pam"
}