[SOLVED] Error or Missing Documentation

[utkonos]

I'm getting most of the API end points into an API client for testing. I have run into an entry that is either an error in the documentation or there is a missing bit of documentation. Or it has been removed and there is still a remnant:

/api2/json/nodes/{node}/execute

If you look in the API docs, you can click on and read this entry for dns:

/nodes/{node}/dns

And this one for hosts:

/nodes/{node}/hosts

But if you click on the link to read the documentation for "execute" between those two above, there is a problem and there is no documentation available.

 

[sterzy]

Hi,

thanks for pointing this out, I'll look into it and report back when I have some more information

 

[utkonos]

Hi,

thanks for pointing this out, I'll look into it and report back when I have some more information

Any idea what the documentation for this endpoint is supposed to be?

 

[sterzy]

Ah sorry, forgot about this thread, yeah if you don't mind reading code you can take a look at the patch I've made [1] and its follow-ups [2].

These should be included in the next release of pve-manager which should fix the issue.

tl;dr: This API endpoint lets you call any number of other API endpoints at once. This made sense in a time before API tokens, as it essentially let you call multiple endpoints without the need to re-authenticate yourself. You could have worked around that by handling cookies, but that would have been cumbersome in many cases. Nowadays, you really want to use API tokens instead, for multiple reasons:

1. You can make any number of requests, without the need of extra authentication handling. Simply add a header to your request.
2. More granular permission handling allows you to give the token only the permissions it needs without the need of setting up a whole new user account.
3. The token can be revoked more easily when stolen, and the accompanying account password does not need to be handled by the client side in plaintext.

[1]: https://git.proxmox.com/?p=pve-mana...;hpb=9d15eb049e6a0ce2f9bac037a63aa3ea61438b97
[2]: https://git.proxmox.com/?p=pve-mana...;hpb=099c4cc20b2027e95e62e3502573c3e35aaeb9fe

 

[sterzy]

If you really really want to use it, here is an example of a curl command that demonstrates how to do so (you'll need to switch the $host, $nodename, and $token variables for appropriate values of course):

curl --location --request POST 'https://$host:8006/api2/json/nodes/$nodename/execute' \
    --header 'Authorization: PVEAPIToken=$token' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "commands": "[{ \"path\": \"dns\", \"method\": \"GET\" }, { \"path\": \"aplinfo\", \"method\": \"GET\" }]"
    }'

This will call the GET dns and GET aplinfo endpoints.

Please be aware that we will likely deprecate stuff like this eventually in favor of API tokens though.

 

[utkonos]

If you really really want to use it, here is an example of a curl command that demonstrates how to do so (you'll need to switch the $host, $nodename, and $token variables for appropriate values of course):

curl --location --request POST 'https://$host:8006/api2/json/nodes/$nodename/execute' \
    --header 'Authorization: PVEAPIToken=$token' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "commands": "[{ \"path\": \"dns\", \"method\": \"GET\" }, { \"path\": \"aplinfo\", \"method\": \"GET\" }]"
    }'

This will call the GET dns and GET aplinfo endpoints.

Please be aware that we will likely deprecate stuff like this eventually in favor of API tokens though.

Understood. I am already using tokens and can see why this endpoint would be deprecated. Thanks!